printIQ Integration toolbox

printIQ Integration toolbox


Integration Toolbox

Getting started with integration and API overview
Access printable attachment at the top or bottom of this article depending on your browser.

Introduction 

When it comes to workflow and integration, everyone’s requirements are unique and, in some cases, are very complex and built up over years of hard work.  The printIQ approach to integration is to enable you to build the workflow that works for your business.  

We do this by providing an integration toolbox filled with tools and plug-ins that enable you to support the workflows within your business.

The aim of this document is to provide a plain English introduction to the technical capabilities of printIQ.  It serves as a starting point from which to then drill down into the lower level details for each touch-point.


Common types of integration

While you are not limited to what you can achieve with integration, we find the most common integrations are based around these main areas:


  • Third-party or in-house developed website or shopping cart
  • Accounting system (Customers, Suppliers and Invoicing)
  • Automated job management and updates
  • CRM package (Customers, quotes and pipeline management)
  • Data capture from other applications or the factory floor



Using the printIQ Directory Monitor

While having one application connect to another via a real time API call is ideal, we realise that it is not always viable.  In some cases, the application or equipment you wish to connect from do not support APIs or it may be that you don’t have IT staff to complete the project.

If this is the case, you may prefer to use the printIQ Directory Monitor module which effectively takes a file (your format or ours), interprets the data and then calls the printIQ APIs on your behalf.  The end result is a smart yet simple approach to integration that requires minimal technical skills from your end.

Some of the common use cases for the Directory Monitor are:

  • Your online ordering system / shopping cart can only produce an XML or CSV file
  • The piece of equipment you are connecting can only work with physical files, i.e. a print queue or outputting actuals from a press.
  • The application you are trying to connect is a locally installed application (as opposed to web based) and has no way of connecting to printIQ in the cloud
  • Your integration is more bespoke and requires custom handling that a single API call cannot support. 


How the printIQ Directory Monitor works

From a high-level perspective, this is how the Directory Monitor application works

INSTALL THE DIRECTORY MONITOR

The Directory monitor is a Windows EXE that is installed on a server or PC within your business.  We install and configure it to connect to printIQ.  The integration is secured by whitelisting your IP address.

FILE LANDS IN THE HOT FOLDER

The folder that the Directory Monitor is watching is effectively turned into a hot folder. As files drop in, the application commences its workflow.

DATA TRANSLATION

There is a standard CSV format that we support for specific functions, e.g. order creation.

If you prefer to use your own format (or where you have no choice), we write an import specification that translates your file into a format that printIQ can understand.  This translation is completed within the EXE so any changes are relatively quick and easy to deploy.

PRINTIQ API CALL

Once the data has been imported, the EXE then makes the printIQ API calls that are configured within the application.

The advantage is that as we are calling our own APIs, the process is robust, and we avoid the learning curve of being new to printIQ

TRANSFER FILE

Once the file has been processed, we move it to a Completed subfolder so that the hot folder is clear.

Where an error is encountered, we can move the file to a different folder and also send email alerts.



Getting started with your integration project

Planning your integration project is where it all starts.  Spending some time to consider what you’re looking to achieve, 
who you need to be involved and how it will all fit together will pay off in the long term.


As a guide, consider the following


STEP 1

Finalise which applications you are looking to connect.
Note, if you’re still in the evaluation phase, ensure the system has modern integration capabilities such as being able to utilise API calls, importing, and exporting of data via Webhooks or at minimal file-based transfers.

STEP 2

Outline the workflow that you wish to implement including the expected results.  Define who will use the workflow and what changes it will mean in a real world scenario.

STEP 3

Identify the touch points you would want to have in place.

STEP 4

Decide who will be involved, including your own resources and third-party suppliers that support the applications you’re working with.

STEP 5

Sanity check to ensure what you are looking to achieve is realistic, minimizes risk and avoids complexity where possible.  The rule of thumb is that fewer touch-points result in better integration.


Integration resources 

Depending on your in-house resources, you have a number of options available for integrating with printIQ.


  • Use your own internal development resource to write interface code to call and receive data from printIQ API’s and/or webhooks.  This is the most common approach with printIQ leading you through the approach and helping out where needed.
  • Use an external Integration specialist company to write interface code. It is commonly used for Switch, XMPie and CRM integrations where you may be best to engage an expert that has done what you are looking for already.
  • Engaging the printIQ development team to complete the integration for you.  In this scenario, we will complete the technical aspects of the project, however, you will still need someone at your end to be responsible for the tasks related to the application you wish to integrate with.



An overview of our APIs 

Within printIQ, we have approximately 200 functions that can be completed via an API call.  Below, we have separated the more common APIs into categories with a brief explanation of what each one does.  From there, we have full technical documentation within our knowledge base.  This is intended as a high-level overview.


RESTful Webhooks to push and post API calls

CREATECUSTOMER

This is both a create and update method to manage the base customer record.  It can be used to push a customer record post creation or to receive the creation request.

CREATECUSTOMERCONTACT

As per above but this applies to the contacts associated with the customer

CREATECUSTOMERADDRESS

As per above but this applies to the addresses associated with the customer

CREATEQUOTE

This is a POST call to push details from printIQ of the quote once it is created

CREATEJOB

This is a POST call to push details from printIQ of the job once it is created

COMPLETEJOB

This is a POST call to push details of the job once the job status is set to Complete

CREATEJOBXML

This is a POST call to send XML details relating to the job when the job is created.  This forms the basis of the info used by a third party application to understand the details of the job

EXPORTPURCHASEORDER

This is a POST call to push details of the PO once it is created

EXPORTINVOICE

This is a POST call to push details of the invoice once it is marked as exported.  We generally use this to write a custom format for a finance package to send the sales invoice data.

DISCARDQUOTE 

EXPIREQUOTE

REJECTQUOTE

This is a POST call to push details of the quote once it has had the status set to Discarded, Expired or Rejected.

Generally, these are used when pushing updates to a CRM to update the opportunity

UPDATEJOBSTATUS

This allows you to update the status of a job to any of the available statuses.

It also allows you to POST job XML details when a job hits a certain status

UPDATEDISPATCHSTATUS

This is a POST call to push the job details once the jobs’ dispatch status has reached a complete status


SOAP/JSON APIs for Quoting

GETLOGINTOKEN

Call to printIQ to request the issuing of a login token that will be valid for up to 2 hours.  You use this token to authenticate subsequent requests rather than logging in on each call

CREATEQUOTEWITHDELIVERY

This allows you to create a new quote.  Generally, it is a SKU based product that is created.  One of the fields is Accept, by setting this to True, the job is created within the same call.  

GETPRICEFORPRODUCT

This is a call to calculate the price for a specific product on the quote. You use this in conjunction with CREATEQUOTEWITHDELIVERY to add a second product to a quote.

ADDDELIVERYTOQUOTE

A call to add delivery details to your quote when building up a quote from scratch

CONFIRMFREIGHTONQUOTE

This calculates the price for freight based on the delivery details added

ACCEPTQUOTE

Separate call to accept a quote that can be called at any point up until the quote has expired.

GETQUOTEDETAILS

Retrieves details regarding any quote within the application


SOAP/JSON APIs for Job Management

GETACCEPTANCEDETAILS

This effectively retrieves job related data in the form of XML as an AcceptanceDetail record is the equivalent to a job.  You will find that the data included is very similar to the Job XML that we push on creation

UPLOADARTWORKURL

Push the URL of files related to a job to this API.  The result is that printIQ then pulls the target file into the job.  This is a more convenient way to submit artwork on a job than a traditional FTP transfer.

UPDATEJOBSTATUS

Push call to update the status of a job to any available status

UPDATEREFERENCEFIELD

Reference fields are custom fields within printIQ that you can use to capture additional data regarding your job.  This is a push call that allows you to update these fields

ADDNOTE

As the name suggests, a push call to attach a note to an existing job

UPDATEJOBQUANTITY

This API call allows you to update the quantity of a job.

UPDATEJOBPARAMETER

This API call allows you to control the parameter values of specific operation parameters.  This is commonly used within a mail type job or used to record actual click rates.


Job based APIs / Production integration events

JOB_CREATED

This is a push call to a third party application to notify that a job has been created.  This normally works in conjunction with the Job XML to send the details of the job with the call

TRIGGER_PREFLIGHT

PREFLIGHT_PASSED

PREFLIGHT_PASSEDWARNINGS

PREFLIGHT_FAILED

A series of calls that first allows you to push an update that a preflight is present on the job and is ready to commence.  

The remaining are POST calls back to printIQ from your preflight application that sends the result.

UPDATE_JOB_FINISH_SIZE

A call that allows you to complete an Edit Job function to update the size of the job. Generally, you would use this when your pre-flight fails as the orientation is incorrect or where there are small discrepancies between the job dimensions and the artwork supplied.

TRIGGER_PROOF

PROOF_SENT

PROOF_APPROVED

PROOF_FAILED

PROOF_READY_TO_SEND

A series of proof related events that first allows you to tell a third party application that a proof is present on the job and is ready to commence

The remaining POST calls allow you to push the results back to printIQ

IMPOSITION_COMPLETED

A POST call from your imposition application that updates the imposition status of each artwork file

RIP_PASSED

RIP_FAILED

POST calls that allow you to update printIQ with the RIP status for each artwork file

TRIGGER_SEND_TO_PRESS

FILE_SENT_TO_PRESS

SEND_TO_PRESS_SUCCESS

SEND_TO_PRESS_FAIL

A series of calls that allows you to send job information and artwork to a DFE queue or hot folder.

ADD_NOTE

A POST call that allows you to add a note to an existing job.  Generally, you would use this to back up one of the previous calls to keep a job history of the integration events

ADD_TASK

A POST call that allows you to create and assign a new task relating to a job.

CHANGE_STATUS

A POST call that allows you to update the status of an existing job

SEND_EMAIL

A POST call that allows you to generate any of the existing Email templates within printIQ.  For example, the order confirmation email

CHECK_COMPLETE_TIMING

This allows a third party application to push timing data relating to a printIQ job.  It mimics the Start/Stop buttons within the application or the barcode scanning.

UPDATE_JOB_DUE_DATE_FROM_TAT

A call to have printIQ refresh the due date of the job by recalculating the turnaround time rules associated with the job elements


Miscellaneous calls

INVENTORY ITEM UPDATE

This is a post call to push inventory item transactions which are generated each time there is an inwards goods, stock pick, stock adjustment transaction

INVOICEDETAILPUSH

This is a data push which triggers when an invoice is exported.  It can be sent to a URL endpoint or written to a folder location



Using our APIs:  Order creation options

The most common integration workflows are based around creating orders within printIQ so that they can be processed through production.  Generally, the order is coming from a third-party application or website with the output being some type of text file or API call.  

To support this, we offer eight different ways of creating an order within printIQ using the integration toolbox.

Note, keep in mind that printIQ has its own built-in web2print portal so you may find that by using the native functionality it may replace many of your existing integration requirements.


Concept

Approach

Direct API call

An order can be created by calling one of the QuoteProcess API methods directly.  The APIs support the creation of an order with one or more products.

The API responds with order confirmation information.

CSV/File into a hot folder

You can write to our CSV format or alternatively, we can create a file specification that matches your file.  From there, you transfer this file into a hot folder.

We have an EXE that you install that is a directory monitor.  It watches for new files and calls the printIQ APIs on your behalf.

CSV upload within printIQ

The same CSV format can be uploaded onto a printIQ Order Upload page where the import takes place from.  The upside here is that you receive real time feeds relating to progress and errors encountered.

Order creation – SKU based

The APIs and file formats support a SKU / Product code based ordering workflow with two options for pricing, either using printIQ standard pricing (based on machine, labour and materials) or a contract/market driven price.

Order creation – Custom product

A CSV file specification can define a custom product where you define the attributes of the product you wish to order.  Again, pricing can be based on the printIQ pricing engine or you can define the price in your CSV.  You can pass the file as an API or via a hot folder.

XMPie / uStore

The uStore integration is based around a standard XML format that resembles a cXML specification.  It is transferred to printIQ via an API push from uStore following the order creation.

Punch-out process

The XMPie integration is an example of a punch out process where a thirdparty ordering application completes the order and pushes the order details to printIQ after the event.

There are numerous examples of this where we can use the CSV or XML format outlined above or we can write to your own specification.

SmartSite – Web Widget

The SmartSite widget is based on taking the smarts of printIQ simplified quoting and making it available on your website or within an external application.  The widget provides the smarts for defining a product and uses the pricing engine from within printIQ.

The widget has its own shopping cart and checkout is from within printIQ.







Data validation and error handling

As thirdparty applications create orders within printIQ, we have a variety of techniques to ensure that data is correct, and errors are handled efficiently.


Data validation

Error handling

Checks and balances

Data file sanity check

Email notification

Screen based visual indicators

Import data validation as each order is created

Task creation and assignment

Order CSV with job details

Real time feeds (screen based)

Screen to review / retry

Custom Izenda reports


Direct API response




A common order creation workflow using API calls

The following is the most common way of creating an order within printIQ with one or more products.


STEP 1

Establish a connection to printIQ using an authorisation token

GetLogInToken

STEP 2

Create the initial order with a single product

CreateQuoteWithDelivery

STEP 3

Add additional products to the order

GetPriceForProduct

STEP 4

Accept the order to create one or more jobs

AcceptQuote

STEP 5

Order creation XML push with job summary

CreateJobXml




Using our APIs:  Managing your jobs using APIs

When it comes to managing jobs, we have some API calls available that allows you to update the job or to push data about the job to an external application.


  • Get job info (GetAcceptanceDetails)
  • Get Job info via a URL request
  • Get Job info via an XML push
  • Update job status
  • Record time on a job, Start and Stop which also updates the status
  • Write a note
  • Send an email (restricted to certain email templates)
  • Update the Due date of a job
  • Refresh TAT / Due date 
  • Update job quantity
  • Update job operation parameter values (commonly called in a mail environment)



An example of job creation and subsequent edit job workflow. 

The following is a step by step example for retrieving information about an existing quote, accepting it with updated quantities and then using an Edit Job API to update the job after it is created.


STEP 1

Establish a connection to printIQ using an authorisation token

GetLogInToken

STEP 2

Locate details of an existing quote to use in the next call

GetQuoteDetails

STEP 3

Accept the quote

AcceptQuote

STEP 4

Modify the job to change quantities and parameters

EditJob



Using our APIs:  Capturing job actuals

When it comes to capturing actual information relating to a job, we find two main scenarios:

  • An external application is being used to manage a digital job by designers or project coordinators.  For example; Jira, Zoho Project, Basecamp, etc. are feeding back time recorded on jobs and / or writing notes and updating statuses.
  • A piece of equipment is passing back actuals such as stock usage, time capture or clicks.  



Integration option

Approach

Using Enfocus Switch

Using Enfocus Switch allows you to tap into the dozens of integration touch-points that we publish in Switch workflows.  It will also allow you to use Switch Configurators provided by your device supplier that will do the majority of the integration work.

Using the Directory monitor to pass files to printIQ

As outlined above, your device or application will output a file to an agreed location.  The DM tool will pick this up, translate it and call the appropriate printIQ API

Calling the APIs directly
  • Using the Production Integration events, you can start/Stop time on a job to capture actual time taken
  • Use the UpdateJobParameter call to pass variable quantities such as press clicks or pack quantities
  • Use the inventory API to create an inventoryItemTransaction (Available from v41)


Using our APIs:  Integrating with your financial system

When it comes to sending data to your accounting system, there are a number of touchpoints that you can make use of.

Keep in mind that printIQ currently supports numerous accounting system integrations ranging from Xero, MYOB (AccountRight, Exonet, Advanced), QuickBooks (Enterprise and Desktop), QuickBooks Online, Sage and Microsoft Dynamics 365.


The standard touch-points are:

  • Customer creation / update push from printIQ
  • Supplier Creation / update push from printIQ
  • Sales invoice push
  • Supplier invoice push


The extended touch-points available for some applications are:

  • Invoice amount due pull 
  • Account on hold due to overdue invoices check
  • Account exceeds credit limit check
  • Create payment push from printIQ
  • Purchase order push


Izenda report writer plug-in


As part of the accounting integration, we have added a plug-in to the Izenda report writer which allows you to create a report that is outputted to a CSV or
XLS format and saved to a folder location.  This plugs into the invoice export process so that you can create your own export file format. 



    • Related Articles

    • Smartsite Implementation guide

      SmartSite Implementation Guide Your marketing website powered by printIQ Contents 1 Introduction: What is SmartSite 2 Why use SmartSite 3 Getting started 4 Under the hood 5 Authentication and security 6 Styling 7 Widget samples 8 Widget configuration ...

    • Sage 50 Integration Documents

      Specialist Paul van Tongeren Introduction The integration to HyperSage is primarily a push from printIQ. This is a manual process requiring the user to export from within a record or to select multiple records from the appropriate area and click the ...

    • Freight Integration Module – NZ Post

      This article is intended for those who have purchased the IQ Freight Integration Module and have an account with NZ post. If this module has not been purchased, please discuss with your printIQ Account Manager. The following details are required for ...

    • API (SOAP) – Send Email

      Introduction You may use SOAP calls to send emails from printIQ. Email templates are configured via Admin / Customise, then the link to Emails   All of the email templates available on your system may be referenced by the following table of ID’s:   ...

    • v46 - ProductUpdated and SalesItemUpdated Webhook

      This Webhook will fire when you set this 2 in Webhook Trigger. What triggers it: When you activate/deactivate SPC session When you upload SPC product. Every product in Product CSV will be part of the payload. If you upload 100 products, it will fire ...