Skip to main content

Announcements to your system

When a declaration that concerns your country is filed, crosses a border or is discharged, ITS can tell your system within seconds. This is optional: without it, your system can still ask ITS for updates. The section Announcements to your system is where you say where ITS should send those announcements.

It has two parts:

  1. Your receiving endpoint: the address of your service. ITS sends announcements to it over HTTPS, and also calls it for the guarantee check.
  2. Network settings (advanced): the addresses your system calls ITS from.

What your system must do when an announcement arrives is in Receiving announcements.

Before you start​

  • You need Organisation admin or Partner in your own organisation. See What each role can do.
  • The section appears only on the Live side of your workspace, so the Secretariat must have approved your Live access. On the Sandbox side there is no endpoint or source address to set.
  • A new endpoint waits for the Secretariat. Nothing you send here changes where announcements go until it is approved.
  • A REC declares an endpoint once per member State it files for, and chooses the Member State in the form.

How to open it​

  1. Open System integration.

  2. Check that Environment is on Live.

  3. Scroll to Announcements to your system, under the card saying that your organisation is live.

    Announcements to your system on Uganda's Live side: part 1, Your receiving endpoint, with the Receiving endpoints table and the Add a new endpoint button, and part 2, Network settings, collapsed

Declare a receiving endpoint​

The receiving endpoint is the address of your service: "Where ITS sends announcements. ITS calls this address only after the Secretariat approves it."

  1. Under 1. Your receiving endpoint, select Add a new endpoint.

    The New receiving endpoint form: Address, How ITS signs in to your endpoint set to OAuth client credentials, Client ID and Token endpoint, with the Cancel and Send for approval buttons

  2. A REC only: choose the Member State this endpoint receives for.

  3. Type the Address of your service. It must start with https://: any other address is marked under the field, The address must start with https://. ITS sends announcements over HTTPS only., and the form is not sent.

  4. Choose How ITS signs in to your endpoint.

  5. For OAuth client credentials, type the Client ID and the Token endpoint.

  6. Select Send for approval, or Cancel to close the form and send nothing.

The form closes and the endpoint appears in the Receiving endpoints table with the status Awaiting approval. There is no other confirmation message. ITS starts calling the address when the Secretariat approves it.

The fields​

FieldRequiredWhat to enter
Member StateYes, for a REC. A State Party does not see it"One endpoint per member you file for. Declare each one separately."
AddressYes"The address of your service, including any gateway prefix. ITS adds the path for each announcement itself, so leave the paths out."
How ITS signs in to your endpointPresetOAuth client credentials: "ITS gets a token from your sign-in server before it calls you. ITS checks the client ID and token endpoint when you send this form." Or My endpoint checks access itself: "ITS calls your endpoint without a token. Your endpoint decides which calls to accept."
Client IDYes, with OAuth"The client ID you created for ITS on your sign-in server. There is no field for the secret: ITS keeps it in its own protected settings, not in this form."
Token endpointYes, with OAuth"The full address of the token endpoint. ITS uses it exactly as you enter it and does not look it up from your sign-in server."

If ITS refuses the form, its message appears in red above the buttons and the form stays open with what you typed. A REC that has no member State to choose reads instead: "No arrangement on file lets this union receive announcements for a member State yet. The Secretariat records the delegation before an endpoint can be declared."

The Receiving endpoints table​

ColumnWhat it shows
AddressThe address you declared
How ITS signs inOAuth client credentials and the client ID, or Your endpoint checks access
StatusSee below
StatusColourMeaning
Awaiting approvalAmberDeclared. ITS does not call it yet
ApprovedGreenThe address ITS calls
SupersededGreyReplaced by a later endpoint of your own. Final
DisplacedGreyStood down because another organisation receives for the country for now, for example a REC filing for a member State. The Secretariat can switch back to it

Things to know before you rely on the table:

  • You cannot edit or delete an endpoint. To change the address, declare a new endpoint. "A new endpoint replaces the old one once it is approved. Old endpoints stay in this list, so you can always see where announcements were sent."
  • Your current endpoint keeps receiving until the new one is approved.
  • The Secretariat can approve an endpoint but cannot reject one. An endpoint that will not be approved simply stays Awaiting approval. If you declared one by mistake, declare the right one and tell the Secretariat which to approve.
  • An empty table reads No endpoints: "You have not added a receiving endpoint yet."

Record your source addresses​

Source addresses are the public IP addresses your system calls ITS from. Recording them is optional: "Add them if your network team needs them recorded."

  1. Select 2. Network settings (advanced) to open it.

  2. Select Add an address.

    The source address form: IP address or CIDR, Note, and the Cancel and Declare address buttons

  3. Type the IP address or CIDR, in CIDR notation, for example 196.201.214.0/24.

  4. Optionally, type a Note, for example "Primary data centre".

  5. Select Declare address. If you select Cancel after typing something, the portal asks Discard your changes? first.

The address is listed at once in the Source addresses table, under Network and Note. It needs no approval. An empty table reads "No addresses added yet."

An address cannot be edited or removed on this screen. If one is wrong, ask the Secretariat how to have it corrected.