Computershare GEMS

The GEMS connector imports data from Computershare GEMS (Global Entity Management System) into Avallone:

• companies, with their addresses, status and capital;
• people;
• shareholdings, as ownership between companies, or between a person and a company;
• appointments, as the positions people hold at companies.

Avallone reads this data through saved searches in your GEMS environment. You choose which saved search Avallone reads for each GEMS schema. See Supported schemas and Saved searches.

How authentication worksCopy Anchor Link

Avallone signs in to GEMS as an API client, not as a GEMS user. It uses the OAuth 2.0 client credentials flow:

1. Avallone sends the API client's client ID and client secret to the GEMS token endpoint, and asks for the gemswebapi scope.
2. GEMS returns a short-lived access token.
3. Avallone sends that token with each request to the GEMS Web API.

Avallone requests a new token when it needs one. Nobody has to sign in or renew access by hand.

Both endpoints are on your GEMS environment's base URL:

The base URL must use HTTPS. Avallone stores the client secret securely, never shows it again, and only sends it to the base URL it was saved with.

Client certificateCopy Anchor Link

Some GEMS environments also require a client certificate. GEMS then uses mutual TLS: when Avallone connects, it proves that it holds the certificate's private key. Avallone presents the certificate on every connection to GEMS, including the token request. It is used together with the client ID and client secret, not instead of them.

A client certificate is optional. Only use one if Computershare asks for it.

Computershare issues the certificate as a .pfx file with a password:

• The file must be a .pfx or .p12 file of at most 32 KB.

• Avallone checks the password when the certificate is saved, and rejects a wrong one.

• Avallone rejects older .pfx files that use legacy encryption. Re-export such a file with modern encryption, then use the new file:

  Copy Text

  openssl pkcs12 -legacy -in old.pfx -nodes | openssl pkcs12 -export -out new.pfx

Avallone stores the certificate and its password securely, and never shows them again. The certificate has an expiry date. Ask Computershare for a new certificate before it expires, because GEMS refuses the connection once it has expired. Avallone shows the expiry date as a warning from 30 days before it.

GEMS environmentsCopy Anchor Link

Each GEMS environment, such as UAT or production, has its own base URL and its own API client. Connecting another environment needs that environment's client secret. It also clears the chosen saved searches, because saved searches belong to one environment. A stored client certificate is kept. Replace or remove it if the other environment uses a different certificate, or none.

Ask Computershare or your GEMS administratorCopy Anchor Link

Send them this list:

1. Register an API client for Avallone that can use the client credentials flow, with access to the gemswebapi scope. GEMS then issues a client ID and a client secret.
2. Confirm the base URL of the GEMS environment to connect, for example the UAT or the production environment.
3. Tell you whether the environment requires a client certificate. If it does, they issue a .pfx file and its password.
4. Create the saved searches Avallone will read, one for each schema you want to import. See What each saved search should include.
5. Share the base URL, the client ID, the client secret and, if there is one, the client certificate and its password. Use a secure channel for the credentials if possible.

Supported schemasCopy Anchor Link

GEMS organizes its data in schemas. Avallone reads these eight:

Company Basics is required, because it holds the GEMS entity ID that every other schema refers to. The other schemas can be added later.

Some schemas only work together:

• Shareholdings and appointments link to people only if Person Basics is also set up. Without Person Basics, no people are imported.
• Add Entity helps Avallone find who each shareholder is. Without it, Avallone only matches shareholders to the companies and people it imports.

Saved searchesCopy Anchor Link

Saved searches are the searches you save in GEMS for a schema. They are specific to each GEMS environment. Avallone lists the saved searches in your environment, and you choose one for each schema.

A saved search decides two things:

• Which records Avallone imports. Avallone imports every row the saved search returns. Use the search's filters to limit the import, for example to the companies Avallone should know about.
• Which columns Avallone can import. Avallone can only import a column the saved search returns.

Every schema also has a default [All] saved search. It returns every column of the schema, with no filters. Use it if you don't need a custom saved search.

Avallone reads the columns of each saved search from GEMS every time its settings are opened. A change to a saved search in GEMS shows up in Avallone without further setup.

What each saved search should includeCopy Anchor Link

Each saved search must include the GEMS entity ID column. Avallone uses it to link the schemas together. It also uses it to recognize a record it has already imported, so a later sync updates it instead of creating a copy.

Columns Avallone has no standard field for can still be imported into custom fields, for companies and for people.

Company BasicsCopy Anchor Link

Entity AddressCopy Anchor Link

Status History and Summary CapitalCopy Anchor Link

Summary ShareholdersCopy Anchor Link

Each row is one shareholding.

A shareholder that holds several securities in one company appears on several rows. Avallone adds their percentages together, up to 100%.

Add EntityCopy Anchor Link

Each row is one entity in your GEMS environment. Avallone matches each shareholder name to an entity here.

Avallone uses the entity type to tell people from companies. A value such as Individual, Person or Natural person means a person. Any other value means a company. Without the entity type, Avallone treats every shareholder as a company.

Person BasicsCopy Anchor Link

First name and last name must be separate columns. Avallone doesn't import a person without both.

By default, Avallone only imports a person who holds a shareholding or an appointment in one of the imported companies. Person Basics usually lists far more people than that. Avallone support can turn this filter off to import everyone the saved search returns.

Company AppointmentsCopy Anchor Link

Each row is one position held at one company.

Avallone turns each position into an officer role, and creates any role your tenant doesn't have yet. Without a position, every appointment gets the role Other.

Dates must use the format YYYY-MM-DD, such as 2024-03-31. Avallone leaves out a date in another format rather than guess it.

Only people are appointed. Avallone skips a company appointed as an officer.