WrapConnector

ExcelWraps can access remote systems through a built-in interface called WrapConnector. This is the main help page for WrapConnector.

Introduction

ExcelWraps is an open system that easily communicates with many other systems. Existing integrations include sending completed units of work to enterprise resource planning systems like SAP, and an Internet-of-things application where ExcelWraps controls and audits the advanced use of torque wrenches.

ExcelWraps provides a simple but very secure method of real-time communication between a wrap and other web server applications called WrapConnector. This page is the main help page for the WrapConnector interface.

  • An HTTP request is used to send a POST or PUT to the remote system, effectively driving it remotely, or a GET to fetch values from it.
  • Any data returned by the HTTP request is in JSON format, and can easily be decomposed by the wrap using ValueAt functions in the wrap template in Excel.
  • To provide convenient but secure login to the remote system, authorization tokens are stored in the WrapConnector definition and used as described below. You can also use many other authentication protocols. If you wish to integrate ExcelWraps with one of your systems using other means of authorization, please contact Client Services.

Example

TBD

Audit trail

All WrapConnector requests are tracked in the audit log. The log includes both the outgoing GET or POST HTTP request and its response. This may help you understand why a connection is not working as expected.

The audit trail contains the following information for WrapConnector requests:

  • The ID of the WrapConnector being used.
  • A timestamp for the operation.
  • The link that was used, with the placeholders replaced by the actual parameters.
  • For Post, the JSON that was sent.
  • The user role that authorized the user to perform the operation.
  • The HTTP status that was returned for the operation, normally 200.
  • The JSON that was received as a result of the operation.

Encryption and authorization

When you open a wrap, communication is 100% encrypted using HTTPS. If the wrap uses WrapConnector to connect to remote systems, all the data that is sent over WrapConnector is also securely encrypted.

Authorization tokens

Each connection from ExcelWraps to a remote system requires a user ID in that system. We recommend that you create a specific user with only the exact permissions required by the related wraps. A mechanism is needed to make the remote system able to authenticate users from ExcelWraps without requiring them to perform a separate login. This is accomplished using a so-called authorization token that is manually generated by the remote system and sent to ExcelWraps in advance. When ExcelWraps later presents the same predefined token as part of a transaction, the connection is considered authenticated and the remote system provides the requested functions without requiring a login. This makes it possible for ExcelWraps to communicate with other systems “behind the scenes” and often even without the user being aware that other systems are being involved.

Authorization tokens are saved on the WrapConnector tab of the ExcelWraps Adminstration dashboard for the wrapsite.

Example: authorization using tokens

There is a need to report time from a wrap into a time-tracking application. In the time-tracking application, a new user is defined to represent this ExcelWraps connection. The new user only has permission to add new records. A unique token is generated in the time-tracking application to represent this login and securely forwarded to ExcelWraps.

ExcelWraps includes the authorization token with each connection request to the time-tracking application, which verifies that it is identical to the token that was previously defined for this “ExcelWraps” user. If the tokens match, a normal login to the time-tracking system can be bypassed and the wraps can register time in the time-tracking application conveniently from within ExcelWraps without the user having to login every time.

Fallback tokens

To avoid interruptions, we recommend that all systems support two concurrently valid tokens. If the first token is not accepted, it has most likely been revoked or expired. If so, ExcelWraps automatically moves on to the fallback token and starts using it instead. The user must keep track of the status of the current tokens in order to obtain a new fallback token every time a previously active token expires.

HTTP Authorization header

Obeying the HTTP protocol, the authorization token is passed to the called system in HTTP’s Authorization header. The token is thus passed in cleartext but over an encrypted connection.

Example required – with/without Bearer?