On Backstage, go to the API module, navigate to API credentials and click on “[API] Credentials”. Then click and edit the value for the fields presented (for example: account, user name, password and event code). The endpoint is pre-configured.
To test the credentials, go to the next step.
The mapping consists of "bridges" that you build between the API and Backstage, so that the data from the API is imported in the relevant Backstage fields (ex. the participants' first names in the API are imported in the "fname" field in Backstage).
Each API comes with pre-set mapping. You can either manually edit the mapping, or import it from a previous event using the same API.
Import mapping from a previous event
- Go to "API Data" -> "Data Configs" on the previous event and click "Export XLS".
- Remove the data configs for which you do not need to import the mapping and save the file
- Import the XLS file in the new event in "API Data" -> "Data Configs".
Manually edit the mapping
Click on the data type. Under "API Data Mappings" you will see all the fields already mapped.
- Edit a field mapping: click on a field and edit the values (you need to specify at least the API field and the corresponding SpotMe field it should be mapped to).
- Create a new field mapping: click on "+" under "API Data Mappings" (you need to specify at least the API field and the corresponding SpotMe field it should be mapped to). Don't forget to save your changes!
- Remove a field mapping: click on the red X on the right of the field.
Once the mapping is edited as desired, make sure to preview the corresponding data type(s) and check that there is content imported for the fields in the "Synced Data" tab (see details below in the Preview section).
For each API field that you map to a SpotMe field in the Data Configs, you need to have a corresponding metadata in Backstage (otherwise the data cannot be displayed in Backstage).
If you map API fields to SpotMe fields that do not exist yet, make sure to create the corresponding metadata (person metadata, session metadata, presenter metadata etc.) in Setup -> Manage metadata. The name of the SpotMe field in the API mapping must correspond exactly to the name of the metadata.
Preview allows to check the data before actually importing it, to make sure that the expected data will be added to the event.
Go to Data Config: all pre-configured Data Configuration types are available here (Participants, Sessions, Sessions, etc.)
Click on “Preview” on one of the Data Config that will be used to download the preview file. Make sure to download the report and check the data:
- The "Stats" tab gives you an overview of the changes
- The "Raw API Data" tab shows all the data that is included in the client's system (with all fields, including the ones that are not mapped)
- The "Synced Data" shows the data as it would be imported
- Duplicated Ids (failed) shows a list of records that are duplicated in the endpoint and that would be then skipped in the sync
If you don’t see the 4 tabs, or see an error message, it means that something is wrong with the credentials you have received from the data provider.
After previewing the data, if there is nothing out of the ordinary, click on Sync Data for each data type you wish to sync.
After syncing, make sure to download the sync report and to check that the data has been imported correctly. The report includes one tab with the following details:
- Status of the sync (if not completed, contact support)
- Received: number of records that we receive from the endpoint
- Unchanged: number of records that we have already created for which there are no changes
- Updated: number of records that we have already created for which there are changes
- Deleted: number or records that are deleted from Backstage
- Invalid: number of records that are invalid
Note: it is necessary to actually sync both Participants and Sessions data before being able to preview and sync Session registrations.
Do not manually sync more often than every hour.
Please note that auto-sync should not be set up unless necessary, since it causes additional stress to our servers, and the maximum frequency is every 15 minutes.
If you are using the API engine package v 1.1.0 or newer: you can enable an auto-sync yourself on any of the data configs in the API.
- Click on a data config, and in "Auto sync frequency" select the frequency you need. If nothing is selected in the dropdown list, the auto-sync will be enabled with a 60 minutes frequency by default.
- On the data configs page, click on "Auto-sync" for the desired data configs.
- You will get a confirmation popup, and the enabled Auto-sync will be highlighted in green.
- The auto-sync will automatically stop 3 days after the end date of the event. If you need it to run longer, please contact App Support.
Please note that the scheduled jobs for the auto-sync are created on the root by default. For big events, make sure to ask to CloudOps which server to use and have the jobs configured to that server (developer access to Backstage is required to edit scheduled jobs).
If you are using the API engine package v 1.0.9 or older: to have an auto-sync set up, please contact App Support and mention which data configs need the auto-sync, to which frequency, and the start and end dates.
You can check when the next sync will run with the following link:
replacing [node] with the root of your event, for example euadmin6, and [eid] with the event id, for example f9792a1ea7e22987af3de9e44200f9f6.
Automated sync reports
If you are using an auto-sync, you may want to receive automated sync reports via email, especially to be warned about any sync error. To set up an automated sync report:
- Click on a data config
- On the right side, "Email Subscribers", click "Create"
- Enter the name of the subscribers list, the event for which you want to get an automated report (Any sync / Error occurred during sync / Never), and add the email address(es) of subscribers
- Make sure to add the subscribers list on each data config for which you want to get an automated report (reports are generated separately for each data config)
- You can also create several subscribers lists, and attach them to different data configs
Please note this functionality is available on data-api 1.1.1 and higher.
Warning! If you need to update the API package(s), please note that the configurations (aka mappings) and credentials will be overwritten.
To avoid overwriting data, you export the configurations and mappings as XLS, update the package and then import the XLS.