Tip: You can use filters for better results
About Incoming Mappings
Inside the Admin panel go to Settings → Incoming Mapping to open the table view of incoming mappings. From there on you have multiple variants of establishing interaction with another system. You can either do it with the help of the setup wizard, which gives you a lot of assistance and the option to manage systems, permissions, and security configurations manually at once.
Connecting systems via setup wizard
The goal of the system connection is to establish a connection between two systems. Information can be transferred from one system to the other, without the user having to do duplicated work. For example, you could transfer ticket information from one system to another one and won’t have to do it for both systems.
1. Create endpoint
An endpoint is where the data for a specific action should be sent from the external system.
- Decide if your endpoint should be immediately activated after the configuration is completed or not.
- Choose a system you want to assign the endpoint. If you don’t have a system created, create one Manage Systems edits.
- Enter a name for your new endpoint. Name your endpoint for the action you want to use. If you for example would use it for Ticket creation you could call it Ticket creation.
- Enter a description for your endpoint.
- Enter a valid path. You could even use your endpoint name.
- Select the method you want to use for the data exchange.
- Select if you want to add a body to the HTTP request. For example, you could select yes if you use a .json file.
| Method | Explanation |
|---|---|
| Get (Read) | The client retrieves a resource from the server. The client should not send data, only retrieve. |
| Post (Add) | The client sends data to the server, so that the server can create a new resource out of it. |
| Put (Create/Replace) | The client specifies a location, and sends some data. If no resource exists on that location, a new one will be created using the data the client sent, if it already exists. It will be replaced by the new data. |
| Patch (Update) | The client sends instructions to the server how to change an existing resource. |
| Delete (Remove) | The client requests the deletion of a resource from the server. |
1.1. Defining endpoints
The next step is to define a permission set for the Endpoint, select an exchange method, and provide the path for the system interaction. You can also create the permission sets directly from this menu by clicking the plus button.
- Select permission or permissions from the dropdown to define the relation to the endpoint.
- Select the method you want to use for the data exchange.
- Decide if a body should be added to the HTTP request.
- Click Next.
1.2 Registering new systems
You can also create a new system directly by clicking the plus button inside the wizard.
- Decide if your new system should be immediately activated after the configuration is completed or not.
- Enter a name for your new system.
- Enter a description for your new system.
- Click Save.
- Proceed with Create Endpoint. You will now be able to select your created system from the dropdown.
2. Selecting permission
Select permissions that will make the Fieldcode endpoint accessible for the external system. Choose from existing permissions or create a new one.
- Select permissions that were already created.
- OR: Create a new permission.
2.1. (Optional) - Creating permissions
- You can also directly create selectable permission while configuring the endpoint definition.
- Enter a name with the correct conventions and click Save.
It would be good if you enter a name that describes the purpose of the permission – for example, for the ones you want to particularly allow or restrict.
3. API key protection
The permission of the Fieldcode endpoint can be granted to the external system with an API key. When using an existing API key, please ensure that the set of permissions included in this API key can be granted to the external system. Otherwise, generate a new API key with a set of permissions suitable for this specific external system.
- Select an existing API key including the permission on your previous step to secure your system connection.
- Click on Generate secure API key if you don’t have an existing API key or you don’t want to use an existing one.
3.1 Adding security configuration
- Decide if your API key should be activated directly.
- Enter a name for the configuration. Name your API configuration based on what you want to secure or what you grant access to with this key.
- Select the permissions you want to give from the drop-down.
- (Optional) – Secure the API key with an Expiration date.
- Click Save.
Do not forget to click SAVE after you have configured everything, otherwise, your configuration will not show up in the table view. The wizard ends after these three steps – you can now continue with the mapping.
The following additional steps are required to finalize the System connection.
4. Adding mapping
If you selected Yes in “Do you want to add a body in the HTTP request?” you will continue with the Select payload step.
4.1. Trigger tab
- You will be asked to choose an example of the payload on your side (not the Fieldcode side).
- In the fine tune schema, you have the option to further configure the payload.
- You can choose between Regular and Expert modes.
- Check if the selected data types for each field of the payload are correct.
- Additionally, you can choose if the selected fields should be optional.
- Additionally, you can choose if the selected fields should be a collection.
- Scroll all the way down to the bottom.
- Click on FINISH STEP.
You will be prompted to choose an Action after finishing the Trigger tab.
4.2. Action tab
- Pick one of the available actions: Create ticket, Create ticket info, Save Document, Save Absence, Update Absence.
- Click on CONTINUE.
- You can now start with the mapping on the Fieldcode side.
- You can either assign whole objects at once or define certain fields.
- You can map fields by typing in a value and using it as a constant.
- OR you can map fields by using already existing values of your payload by using the typing as a search through your payload.
- Click on FINISH STEP.
- If you see the green success prompt on the left bottom, your mapping went through successfully.
The system connection is now in a completely configured state. You now have various edit options to further fine tune the incoming mapping.
5. Editing options
These steps shouldn’t be necessary if you already went through the wizard completely, including actions and triggers.
5.1. Trigger tab
The trigger tab includes the edit endpoint, the upload payload, and the fine-tune schema steps.
- Upload payload is where the user can upload an example of the payload file that will receive from the external system. Can be in a .json or a .txt format. This step is required only if the user selected yes on the HTTP body question while creating the endpoint.
- Fine-tune schema is a visualization of the payload that was uploaded. The system processed the data of the file, the type of each field, and if it is a collection. Users can review and also apply some validations. The data of the fine-tuned schema will be available on the drop-down of the mapping to be used to map the fields of Fieldcode. This step is required only if the user selected yes on the HTTP body question while creating the endpoint.
5.1.1. Edit endpoint
It will be preselected by default if you used the wizard, so you can directly skip to Select payload.
- Decide if your new system should be immediately activated after the configuration is completed or not.
- Enter a different name for your endpoint.
- Enter a different description for your endpoint.
- Select a different system name from the drop-down.
- Select a different permission set from the drop-down.
- Select a different method for the endpoint.
- Insert a different endpoint path.
- Click on Continue.
5.1.2. Select payload
- Drag & Drop another payload file from your desktop or click Choose file to choose a file from the explorer (eg. a .json file or .txt file).
- Click on Continue.
5.1.3. Fine tune schema
- What you see here is the visualization of the payload from the previous step.
- You can now change things if they don’t get recognized correctly.
- Click on FINISH STEP after you have done so. Refer to the instructions above.
5.1.4. Group definition
- You can group your incoming mapping payloads based on:
Default: (Not Python)
Ticket: (Python)
Custom: (Python)
5.2 Action tab
The action tab includes the choose action and define action steps.
- Choose action is where the user chooses the action that needs to be triggered with the endpoint that was created in the previous step. Depending on the action there will be different fields that will need to be mapped in the next step.
- Define action is where the user can map the Fieldcode fields of the action that was chosen. Users can choose to map the field with one of the fields of the drop-down (fields from the fine-tune schema/payload example) and also can type to search on the drop-down. Another way to map the field is for the user to type the input of their preference and confirm it to choose from the dropdown as a constant.
5.2.1. Choose action
- Select an action from the drop-down list.
- Click on CONTINUE.
5.2.2. Define Action
- Make changes to the mapping, eg. assign objects differently or define certain fields differently.
- Scroll to the bottom and check if the ones with an asterisk are recognized.
- Click on FINISH STEP.
6. Editing Different Parts of the System Connection
6.1. Editing Systems
- Click Settings → System Connection → Systems.
- Click on the system you want to edit in the table view.
- Edit the System status, if wished.
- Edit the System name, if wished.
- Edit the System description, if wished.
- Refer to the specific heading further above, if you feel unsure about your edits.
6.2. Editing System Configurations
You can delete System Configurations by clicking on the trash button of an item in the list.
You can have the current API key displayed by clicking on Show API key and clicking on COPY TO CLIPBOARD.