In THRON you can map or associate identifiers to contents, tags, groups and User to facilitate their management and retrieval. 

The ExternalID is one of the identifiers you can associate to your platform elements in THRON. The other ones are THRON Id and the PrettyID.

 

Index

• What is a ExternalID
• Content ExternalID
• Tags ExternalID
• Groups and Users ExternalID

 

What is the ExternalID

The External ID is used to identify a content, a tag, a group or a user through the association of a unique key:value combination for search purposes in THRON DAM PLATFORM or via API, instead of the THRON ID. In this way, you can associate these entities with an identifier consistent with your naming convention, without the need to search them through the THRON ID.

You can set the ExternalID only via API.

The ExternalID has to be compliant with the following constraints:

• Maximum number of characters: key 50, value 200
• Key can not contain characters: §/$&#<>"?*:\|
• Can not contain spaces
• It must be unique in the platform

To identify a content, a folder or tag through a human-readable label or to build SEO oriented urls, you can also use the PrettyID. Read this article for more details about the PrettyID: HOW TO USE THRON PRETTYIDS FOR CONTENT, FOLDERS AND TAGS.

Here below you find a guide about how creating, deleting and searching for ExternalIDs for Contents, Tags, Groups and Users.

 

Content External ID

You can create, edit and delete for Content External IDs via API and search using External ID both from THRON DAM PLATFORM and via API.

 

External ID entry

Using the addExternalId service, you can associate an External ID to a content.

 

POST: https://<clientId>-view.thron.com/api/xcontents/resources/content/addExternalId/<clientId>/<xcontentId>

{ 

  "externalId": { 
    "description": "Your External ID description", 
    "key": "Your key", 
    "value": "Your value" 
  } 
} 

 

Before proceeding to add an External ID, you can check whether it already exists via the verifyExternalId service.

Note: you can associate a maximum of 100 External IDs to a content.

 

External ID removal

Using the removeExternalId service, you can remove the External ID of a content.

 

POST: https://<clientId>-view.thron.com/api/xcontents/resources/content/removeExternalId/<clientId>/<xcontentId> 

{ 
  "externalId": { 
    "key": "Key to delete", 
    "value": "Value to delete" 
  } 
} 

 

External ID editing

To change the External ID of a content, you need to:

• add the new one with the addExternalId service;
• remove the one that need to be replaced with the removeExternalId service.

 

Searching for contents via External ID

Using the search service, you can search for a content using its External ID instead of its alphanumeric xcontentId.

 

POST: https://<clientId>-view.thron.com/api/xcontents/resources/content/search/<clientId> 

{
	"criteria": {
		"ids": [
			"Your External ID by entering key:value"
		]
	},
	"responseOptions": {
		"returnDetailsFields": [
			"locales"
		],
		"resultsPageSize": 10,
		"sort": [{
			"lastUpdate": {
				"order": "asc"
			}
		}]
	}
}

 

Searching for content via External ID in THRON DAM PLATFORM

In THRON DAM PLATFORM, you can search for a content by its External ID, using the "Content" mode in the search field. 

 

Tags External ID

You can manage Tags External IDs via API.

 

External ID entry

Using the addExternalId service, you can associate an External ID to an existing tag.

 

POST: https://<clientId>-view.thron.com/api/xintelligence/resources/itagdefinition/addExternalId/<clientId>/<classificationId>/<tagId>

{ 
  "externalId": { 
    "key": "Your Key", 
    "value": "Your Value" 
  } 
} 

Note: a maximum of 200 External IDs can be associated with a tag.

External ID removal

Using the removeExternalId service, you can remove an External ID from a tag.

 

POST: https://<clientId>-view.thron.com/api/xintelligence/resources/itagdefinition/removeExternalId/<clientId>/<classificationId>/<tagId>

{ 
  "externalId": { 
    "key": "Your Key to remove", 
    "value": "Your Value to remove" 
  } 
} 

 

External ID edit

To change the External ID of a content, you need to:

• add the new one with the addExternalId service;
• remove the one to be replaced with the removeExternalId service.

 

Searching for Tags via External ID

 

Using the list (POST), listget (GET), detail (GET) services, you can search for a tag using its External ID instead of its tagId.

• With API list you can perform a more complex search in POST mode (you can find all available parameters in the service model).
• With API listget you can perform a more direct search in GET mode.
• With API detail you can get all the information related to a specific tag in GET mode.

 

Groups and Users External ID

 

To manage groups and users coming from an external Identity Provider, you need to associate an Extrenal ID to each one of them to enable their mapping.

 

With THRON SAML Connector this activity will be managed automatically. Read the article HOW TO CONFIGURE SAML CONNECTOR for more details.

 

In specific contexts, it may be necessary to manage this task externally. In these cases, you can refer to the following APIs.

• To update groups External ID you need to use updateExternalId service:
  
  POST: https://<clientId>-view.thron.com/api/xsso/resources/usersgroupmanager/updateExternalId/<clientId>/<groupId>

  { 
    "externalId": { 
      "externalType": "SAML", 
      "id": "Your External ID" 
    } 
  } 
  

• To update users External ID you need to use updateExternalId service:
  
  

  POST: https://<clientId>-view.thron.com/api/xsso/resources/vusermanager/updateExternalId/<clientId>/<username> 

  { 
    "externalId": { 
      "externalType": "SAML", 
      "id": "Your External ID" 
    } 
  }