Connector Control Blocks

Within the Scribe Map creation canvas screen, add in the connections that are needed to build out your Scribe Map by clicking “Add Connection”.

In the dialogue box, the connections that you have previously configured on your instance will be available to add to the map – one of which, will be Workbooks. 

Select it from the list, then click OK. From here, the Workbooks Connector is available to use with any of the following Control Blocks in your map:

• Query: A Query block is always the first step in a Scribe Map. It allows you to find a set of records from a source system. Using the Workbooks Connector, this type of block can return any of the record types from Workbooks that you are licenced for. The number of records returned can be controlled by several mechanisms:
  • Filters can be applied to limit the query results to matching records e.g. only return People, where the Town = London.
  • Net Change can be used to limit the query to results that have changed since the last time the map ran. See here for further information on Net Change.
  • Connection Specific: When you configured the connection, there are settings to control Page Size (the number of records to return on each query) and Max Pages (the number of pages to query).
• Lookup: A Lookup block can be used anywhere in a Scribe Map except the first step. It should be used to return a singular record. If more than one record is found from a Lookup, you may experience undesired results in your map or an error. There is no concept of a “loop” with this type of block (see “Fetch” below if you need to return more than one record and process all records found). When running through a map, the Lookup block is designed to pull in extra data that is related to the record currently being processed from the Query block.
  • For example – find the Campaign Membership Id for the Status of “Interested” for a given Campaign Member on a given Campaign. The Id is specific for each Campaign.
  • Using a Query block to find all Campaign Members, use a lookup block as the next step with three filters Campaign Member Id, Campaign Id and Campaign Member Name to return the Id of the Status assigned to that Campaign Member.
• Fetch: A Fetch block can be used in a similar way to a Lookup block to return related records. However, unlike a Lookup block, it has the capability to return multiple records and then loop over each result. Again, this type of block can be used anywhere within a Scribe map, except the first block.
  • For example, using a Query block to find all Organisations. A fetch block could be used to find all People related to that Organisation and process those records within the context of the Organisation being processed.
• Create: A Create block is used to create records of any record type in Workbooks that you are licenced to use. The record types available are governed by the licence type of the user that the API Key belongs to. For example, if the API Key is created as a User that does not have a Workbooks Business licence, you will be able to create Invoices and Credit Notes with corresponding Line Items via the connector. For each record type, consider any system required fields for the selected entity, alongside any fields that are specific to your database.
• Update: An Update block is used to update records of any record type in Workbooks that you are licenced to use. As per the Create block, the connector will only allow you to update record types that the API Key is licenced to use. Again, for each record type, consider any system required fields for the selected entity, alongside any fields that are specific to your database. To update a record in Workbooks, an Id & Lock Version of the record that you are trying to update is required. A worked example is provided here.
• Delete: A Delete block is used to simply delete records of any record type in Workbooks. The connector will only allow you to delete records that the API Key has delete permissions for. Like an Update block, the connector requires a record Id & Lock Version to delete a record.
• Update/Insert: An Update/Insert block is a merge of the Create and Update blocks. This type of block allows you to specify an Id & Lock Version, and thus will automatically update the record if specified. If not specified, the block will automatically create a new record for you of the selected entity type. This type of block needs to be used with a Query, Lookup or Fetch type block to return the Id & Lock Version that can then be passed to the Update/Insert.
• Convert: A Convert block has a very specific use case. It is used to move File data (“blobs”) from one system to another creating an Attachment record in Workbooks, which is “attached” to a parent record under the Files tab. It is also possible to use this block to map to a File or Image type Custom Field. Please contact us if you have a use case for this type of integration as not all scenarios are supported.

A basic worked example for the Workbooks Connector can be found here. For further information on Control Blocks in Scribe, see here.