Tip: You can use filters for better results
How to establish a system connection
Inside the Fieldcode Admin Panel go to Settings → System Connection to open the table view.
From there on you have multiple variants of establishing interaction with another system.
You can either do it with the help of the wizard, which gives you a lot of assistance, or manage systems, permissions, and security configurations manually.
Both approaches are described below.
How to connect systems with the three-step-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.
- Insert 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.
- Insert a description for your endpoint.
- Insert 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. |
How to define the endpoint
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.
How to register the new system
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.
- Insert a name for your new system.
- Insert 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. Select 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.
(Optional) How to create permissions
- You can also directly create selectable permission while configuring the endpoint definition.
- Name it 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. Secure with API key
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 How to add a security configuration
- Decide if your API key should be activated directly.
- Insert 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. Add 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.
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 ability 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.
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.
Editing options
These steps shouldn’t be necessary if you already went through the wizard completely, including actions and triggers.
a) Trigger tab edits
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.
b) Selected endpoint edits
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.
- Insert a different name for your endpoint.
- Insert 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.
c) Selected payload edits
- 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.
d) Fine tuned scheme edits
- 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.
e) Action tab edits
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.
f) Chosen action edits
- Select an action from the drop-down list.
- Click on CONTINUE.
g) Defined action edits
- 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.
h) Edit different parts of the system connection
i) Edit 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.
j) Edit system configuration
You can delete System Configurations by clicking on the black trash button of an item in the list.
You can show the current API key by clicking on Show API key and clicking on COPY TO CLIPBOARD.