Integration Setup - REST

If you're using Vizlib Writeback Table with Vizlib Server, you'll need to set up and select an Integration to store your data and any changes you make. Integrations allow you to connect Vizlib products with your existing solutions (e.g. a database) to improve data sharing. Integrations are configured in the Vizlib Management Console (VMC).

Vizlib Writeback Table can integrate with different data sources, and we're going to use REST in this example. REST APIs can be configured to work with an Integration (which requires you to install Vizlib Server) or a Destination (which doesn't require Vizlib Server). If you're working with larger data sets, we recommend using an Integration, and this article can be applied to integrate with all REST APIs. You can find a list of examples in the Introduction page here.

This topic contains the following sections:

• Before you Start - Checklist

• Adding an Integration

• Adding a Destination

• Adding Writeback Settings

• Working with Vizlib Writeback Table - Data Load Updates

• Vizlib Writeback Table - Further Reading

Before you Start - Checklist

Before you add an integration, you'll need to make sure you have all the information and permissions you need. Work through all the items in this list and then you'll be ready.

• Installations - Vizlib Writeback Table and Vizlib Server should be installed before you start. We have online tutorials for installing Vizlib Server and Vizlib Products to help you (Vizlib Products are all installed in the same way, so while the tutorial uses Vizlib Library, it can also be used for Vizlib Writeback Table).

  Note: If you haven't installed any Vizlib products before, please install the product (Vizlib Writeback Table) then install Vizlib Server. If you have already installed Vizlib Server, please perform a restart after installing Vizlib Writeback Table.

• VMC login / Password - to create and configure the integration, REST destination and check the audit trail. The VMC is installed as part of Vizlib Server.

• REST URL endpoint - to enter when you're adding the integration.

• REST Operation - to enter when you're adding the integration. GET, PUT, POST and PATCH are supported operations and are entered in the field Default Method.

• Reload Option - for configuring Writeback settings.

• App name - the app you want to connect to the destination. You can create a new app, or re-configure an existing one.

• Authentication details - to add authentication information in the VMC. Choose from Basic (a username and password), Token (a token is generated and sent with the request), or a Certificate (a pfx or pem certificate holds the authentication information).

• API Payload / Parameters / Header- If you need to set up a Payload format, add Parameters to send with your request or configure Header information, you can enter these in the VMC.

• Security Rule - to set up secure access for a destination, a security rule should be configured in the VMC. See our article here for more information on setting up a security rule.

Adding an Integration

The first step to connecting is to add or configure an integration.

• Log in to the VMC. You should see the dashboard, with all your current integrations listed in the top left panel (Figure 1). The symbol   indicates a successful setup, and   indicates a setup error.

Figure 1: VMC Dashboard Integrations, with Integrations and System Settings >Integrations highlighted

• Go to System Settings, then click Integrations (see Figure 1) to open the Integrations homepage (Figure 2). Integrations with errors are indicated by .

Figure 2: Integrations Page

• Click Add Integration to open the pop-up screen (Figure 3).

• Select rest as the Type, and enter a unique Id. This will be displayed in Vizlib Writeback Table, so keep that in mind when you're creating it.

• Enter your REST URL endpoint, and the Default Method you want to use.

Figure 3: Add Integration

Figure 4: REST Integration Example

• Click on Add Integration when you're finished, and click Restart to save your settings. You should see the new integration listed in the dashboard.

  Check on Integration Status and Errors: Your integration should display the green tick icon in the dashboard before going to the next step. If it's showing an error in red, follow the advice in the message (Figure 4).

Figure 4: Integration Completed Successfully

Adding a Destination

Now, you'll need to add a Destination, which is the data source for your Writeback table.

Note: By default, an auto-lock is triggered when a writeback operation is performed on a destination, and stays in place until the operation completes. You can enable the Allow Locking setting in Access and Security if you'd like to extend the locking function.

• In the VMC menu, click on Writeback Settings, then Destinations and Security. You should see the list of current destinations displayed on the page (Figure 5).

Figure 5: Destinations

• Click Add Destination and you'll create a new entry. Click on the destination ID to add your destination data (Figure 6). Your destination will already have an ID which is generated from the last entry in the table. You'll be able to change this in the next step.

Figure 6: Destination Fields

Figure 7: Add REST Destination

• Enter a destination Id, then go to the Writeback Settings panel and select REST as the Destination Type (Figure 8).

  Check on Destination ID: Destination ID has to be a unique value, or you won't be allowed to save your changes.

Figure 8: Writeback Settings

• Select the Destination Type as REST, then choose one of the Reload Options (No Reload, Reload App, Partial Reload App, Reload Task).

  Check on Reload Options: Reloading the app means when data is written back to the destination it is immediately available to other users, so you'll probably have to pick an option which enables reload. You can find more information in our article here. Reload Task is set in the Qlik Management Console, you can find more information here.

• Add the writeback App you want to use. Apps are listed alphabetically with the App ID displayed. The app id is intended to make it easier for you to find an app you need to use, or one you've used before.

Now you can configure your destination in the Destination Settings panel (Figure 9).

Figure 9: Destination Settings

• Choose the integration you created from the list in REST Integration.

• Enter the REST URL endpoint in the Path input field. The path will be added to the URL which is defined the REST integration.

• Enter the Method you want to use, and choose whether to Send all rows (sending all rows in the Vizlib Writeback Table or only new or updated rows).

• Select an option from the Authentication panel (Figure 10) which means there'll be a check on your user credentials when a connection is attempted. The options are None (No authentication), Basic, Token, or Certificate.

Figure 10: Authentication

• If you've chosen PUT, POST or PATCH as your method, you'll see the Payload panel appear (Figure 11). Payload settings define the format for the body of the API request and response. The formats are JSON (In JSON notation, Form (as a form), or asParams (a set of Parameters). You can also choose to send the payload as an array or put the data into page format (Paginate).

  Note: If you choose GET, you don't need to select a payload or specify how it is sent. The data will be sent as query parameters in the request. If you send multiple rows of data within a writeback operation, for GET, a separate request will be sent for each modified row.

Figure 11: Payload

• If you need to enter specific parameter or header information, use the Params and Headers panels. (Figures 12 and 13). Click on Add Param or Add Header, then enter the Key and the Value.

Figure 12: Params

Figure 13: Headers

• If you need to lock the data structure that's sent from your writeback table to your destination, you can do this in Fields Validation (Figure 14).

  Note: Writeback operations using this destination must contain exactly the same field names as defined here.

• Enable the setting using the Validate Fields slider, then click on Add Field. You can then enter the field name, and choose Allow null to permit null values.

Figure 14: Fields Validation

Vizlib Writeback Table has a default auto-lock function which is activated when a writeback operation is triggered. You can also use the Locking settings (Figure 15) to extend the locking function for the destination. If you enable Allow manual locking, the destination will lock when you start to input data, and unlock the table when you have finished When locking is enabled, an icon appears in Vizlib Writeback Table.

Figure 15: Locking

• Select Allow manual locking, then choose either Lock only the current destination, or Use Lock Group. You can find out more information on lock groups here.

• You'll also be able to select a Concurrency mode. Auto-Lock means the destination is locked when an operation completes, while Queue means all pending updates will be "queued" and completed before the data is re-loaded. This option is helpful for managing updates from multiple users for a single destination. You can find out more information on queued writeback here.

If you need to restrict which users can work with the destination, you can do this with Access & Security settings (Figure 16).

Figure 16: Access & Security

• Check Secure Destination to enable secure access if you need it.

  Note: This setting is configured with a security rule to allow access to the destination, so users won't be granted access automatically if Secure Destination is enabled. You can find out more about security rules in our article here.

• You can choose to make the destination Public if you want other Content Admin users to be able to re-use it, or Private if you want to limit re-use to the creator (you), Admin and Root Admin users.

• Enable Audit trail if you want to create an audit trail for the destination.

  Note: You can access audit trails on the Writeback Audit page of the VMC, there are instructions on working with audit trails here, and you can also watch a step-by-step video tutorial on setting up an audit trail here.

• Click Add Destination to save your destination in the VMC.

Adding Writeback Settings

Now, you need to go to Vizlib Writeback Table and configure your app to write back to the destination. You'll find these settings in the property panel under Destinations.

• Open your Qlik Sense Hub and find the Vizlib Writeback Table sheet you'd like to work with.

• Open the sheet in Edit mode, then go to Writeback Settings > Destinations in the property panel.

• Click on Vizlib Server in Pick Destination (Figure 17).

Figure 17: Server Destination

• Select a Writeback Destination from the drop-down (Figure 18). This is where your data will be saved.

  Note: REST destination paths follow the structure Destination|REST

Figure 18: Destination Path

• Click Done to save the changes to the sheet.

• When you've completed the changes and saved them, you'll be able to write back to the destination you've configured.

Working with Vizlib Writeback Table - Data Load Updates

Now you've completed the setup, you will need to update your data load script to make sure data is loaded correctly back into the app, otherwise it will look like the operation isn't completing.

The data load script is part of the Qlik Sense environment, you can find out more about editing the data load script in a Qlik Sense app here.

Qlik Sense also have a REST connector, which is used to help load data from REST data sources into Qlik Sense. You can read more about the REST connector here.

When you complete these steps, the table will be loaded back into the app correctly and you can start to use Vizlib Writeback Table to help make the most of your analytics solution.

Vizlib Writeback Table - Further Reading

You should now be able to start working with Vizlib Writeback Table if you've completed all the steps in this article without any errors. We have a Troubleshooting reference guide with hints on how to resolve any known issues and an Introduction article containing information on webinars, basic operations and a summary of all our other articles for Vizlib Writeback Table.