Fieldcode Manual

Tip: You can use filters for better results

Recommended for advanced users

System connection setup doesn't require a developer to be involved - however - configuration is suggested for advanced users of our applications.

Inside the 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 systemspermissions, and security configurations manually.
Both approaches are described below.

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.

An endpoint is where the data for a specific action should be sent from the external system.

  1. Decide if your endpoint should be immediately activated after the configuration is completed or not.
  2. Choosesystem you want to assign the endpoint. If you don’t have a system created, create one Manage Systems edits.
  3. Entername 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.
  4. Enterdescription for your endpoint.
  5. Entervalid path. You could even use your endpoint name.
  6. Select the method you want to use for the data exchange.
  7. Select if you want to add a body to the HTTP request. For example, you could select yes if you use a .json file.
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.

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.

  1. Select permission or permissions from the dropdown to define the relation to the endpoint.
  2. Select the method you want to use for the data exchange.
  3. Decide if a body should be added to the HTTP request.
  4. Click Next.

You can also create a new system directly by clicking the plus button inside the wizard.

  1. Decide if your new system should be immediately activated after the configuration is completed or not.
  2. Entername for your new system.
  3. Enterdescription for your new system.
  4. Click Save.
  5. Proceed with Create Endpoint. You will now be able to select your created system from the dropdown.
Naming for system connections

The system name should only contain alphanumerical characters and can only contain the special characters underscore and hyphen
(except at the word begin).

Select permissions that will make the Fieldcode endpoint accessible for the external system. Choose from existing permissions or create a new one.

  1. Select permissions that were already created.
  2. OR create a new permission.
  1. You can also directly create selectable permission while configuring the endpoint definition.
  2. 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.

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.

  1. Select an existing API key including the permission on your previous step to secure your system connection.
  2. 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.
  1. Decide if your API key should be activated directly.
  2. 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.
  3. Select the permissions you want to give from the drop-down.
  4. (Optional) – Secure the API key with an Expiration date.
  5. 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.

If you selected Yes in “Do you want to add a body in the HTTP request?” you will continue with the Select payload step.

Equal scheme requirement for .jsons

Please be advised that the payload files (.json) need to have the same scheme as the fine-tune scheme of the payload example.

  1. You will be asked to choose an example of the payload on your side (not the Fieldcode side).
  2. In the fine tune schema, you have the option to further configure the payload.
  3. You can choose between Regular and Expert modes.
  4. Check if the selected data types for each field of the payload are correct.
  5. Additionally, you can choose if the selected fields should be optional.
  6. Additionally, you can choose if the selected fields should be a collection.
  7. Scroll all the way down to the bottom.
  8. Click on FINISH STEP.

You will be prompted to choose an Action after finishing the Trigger tab.

  1. Pick one of the available actions: Create ticket, Create ticket info, Save Document, Save Absence, Update Absence.
  2. Click on CONTINUE.
  3. You can now start with the mapping on the Fieldcode side.
  4. You can either assign whole objects at once or define certain fields.
  5. You can map fields by typing in a value and using it as a constant.
  6. OR you can map fields by using already existing values of your payload by using the typing as a search through your payload.
  7. Click on FINISH STEP.
  8. If you see the green success prompt on the left bottom, your mapping went through successfully.
Map fields with astersisks (*) cannot be skipped

You cannot skip map fields with asterisks (*) since they are essential for the system connection to work intially.

The system connection is now in a completely configured state.

These steps shouldn’t be necessary if you already went through the wizard completely, including actions and triggers.

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.

It will be preselected by default if you used the wizard, so you can directly skip to Select payload.

  1. Decide if your new system should be immediately activated after the configuration is completed or not.
  2. Enter a different name for your endpoint.
  3. Enter a different description for your endpoint.
  4. Select a different system name from the drop-down.
  5. Select a different permission set from the drop-down.
  6. Select a different method for the endpoint.
  7. Insert a different endpoint path. 
  8. Click on Continue.
Endpoint path change or endpoint permission change = New endpoint link + new API key

If you change the endpoint path or the permissions of the endpoint please make sure to send out the new endpoint link and an API key that includes the new permissions.

Equal scheme requirement for .jsons

Please be advised that the payload files (.json) need to have the same scheme as the fine-tune scheme of the payload example.

  1. 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).
  2. Click on Continue.
  1. What you see here is the visualization of the payload from the previous step.
  2. You can now change things if they don’t get recognized correctly.
  3. Click on FINISH STEP after you have done so. Refer to the instructions above.

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.
  1. Select an action from the drop-down list.
  2. Click on CONTINUE.
  1. Make changes to the mapping, eg. assign objects differently or define certain fields differently.
  2. Scroll to the bottom and check if the ones with an asterisk are recognized.
  3. Click on FINISH STEP.
Please consider the following when doing edits:
  • You cannot edit permissions after they have been created.
  • You cannot edit security configurations, only delete them, after they have been created.
  • If you want to edit systems and everything else that belongs with it manually (except permissions and security configs)
    you always have the possibility to do so.
  1. Click Settings → System Connection → Systems.
  2. Click on the system you want to edit in the table view.
  3. Edit the System status, if wished.
  4. Edit the System name, if wished.
  5. Edit the System description, if wished.
  6. Refer to the specific heading further above, if you feel unsure about your edits.

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.

Was this topic helpful?
0 out of 5 stars
5 Stars 0%
4 Stars 0%
3 Stars 0%
2 Stars 0%
1 Stars 0%
How can we further improve this topic?
Please provide the reason for your vote. This will help us improve this topic.