The importer uses a set of End Points to create contact and team articles. It will also hide any contacts no longer present in the source data. The terms "team" and "department" are used interchangeably throughout this article and in the End Points, although the template type is always called "Team".
Note that the importer does not update article content (text and images). It creates content, updates mapped fields in article extras, and switches articles off. This means you can edit the article body text directly without changes being overwritten.
The Contact and Team templates can be used without the importer - you can create content directly in iCM as you usually would.
Overview
The importer is designed to take contact and department data from a source outside of iCM and create article content. The main goss.contactdirectory.v1.import End Point could be run as a scheduled task.
When you set up the importer you will need to write an End Point to fetch the contact data, arrange it into a suitable structure, then create the required articles. The importer is designed to create new articles for contacts and departments that don't already exist and update existing articles with a new import date (held in the article extra tabs).
The importer expects your contacts to have some sort of unique ID and something to identify the team they work in. Teams may be identified by their name, which can be taken from your contact information.
Once the import has completed the importer invokes the goss.contactdirectory.v1.clean End Point to turn off any articles that have not been updated/included as part of the import. This effectively removes contacts that are no longer present in the source data.
This diagram gives an overview of how the importer End Points interact. The example testImporter is called asynchronously by import. The result is then passed to the clean End Point.
End Points
import
This End Point manages the import. It could be scheduled to run nightly if you are importing data from another system. It requires the following parameters. The reference will be added to the article extras of the imported content in the "Import source" field.
getConfig
This End Point holds the following information.
| Property | Description |
|---|---|
| contactTemplateID | The ID of the Contact template (found in the iCM template definitions section) |
| departmentTemplateID | The ID of the Team template (found in the iCM template definitions section) |
| apiKey | An API Key with the ability to create and update content in iCM |
| version | The product version (eg "v1") |
Your End Point
This End Point is called by the import End Point to process the data. It will be bespoke to your data and data source. An example is included in the initial installation at goss.contactdirectory.v1.example.testimport.
The End Point is responsible for:
- Parsing the input data regardless of source or format into a known structure, using utils.createDepartment and utils.createContact and mapping information about each contact into the relevant article extra fields
- Updating the content in iCM using the update End Point
- Handing control back to the caller with either a success or failure status
A typical importer End Point would use the following parameters:
findArticle
This End Point will return an existing Contact or Team article if one has already been imported, or return an empty article structure for the relevant template. Existing articles are found by searching the SOLR article collection for articles with the same template ID (ie this distinguishes between contacts and teams) plus the source and import ID.
clean
This End Point is invoked at the end of the contact directory import process. It is responsible for locating any articles (using the Contact and Team templates) beneath the configured root which have ;not been updated. Articles that have not been updated have their display schedule set to "Off".
It is called with the following parameters:
Share this page
