Integration Toolbox
Getting started with integration and API overview
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.
While you are not limited to what you can achieve with integration, we find the most common integrations are based around these main areas:
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:
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. |
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.
STEP 1 |
Finalise which applications you are looking to connect. |
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. |
Depending on your in-house resources, you have a number of options available for integrating with printIQ.
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 |
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. |
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 |
|
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 |
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.
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
|
When it comes to capturing actual information relating to a job, we find two main scenarios:
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
|
|
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:
The extended touch-points available for some applications are:
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.