-
Notifications
You must be signed in to change notification settings - Fork 20
Getting Started with intacctws php
intacctws-php is a set of php classes that "wrap" the Intacct API for invocation over Web Services. The objective of these classes is to unburden developers from dealing with the mechanics of communicating with Intacct and from generating and reading Intacct XML documents. By including these classes in your integration project, you should be able to interact with Intacct using a few simple methods.
Let’s walk through how you would use the library to make a call.
First, you would need to include the necessary class files in your code. Two classes that you will always use are “api_session” and “api_post.”
require_once '../api-classes/api_session.php';
require_once '../api-classes/api_post.php';
You would of course set the paths to the file structure of your web server.
If you are using the readView API method with runtime filters, you will also want to include the “api_viewFilter” and “api_viewFilters” classes.
require_once '../api-classes/api_viewFilter.php';
require_once '../api-classes/api_viewFilters.php';
After including your class files, you need to gather up your credentials either from a secure location on your server or passed in from some external process. You pass these into an instance of the session class using either the company credentials:
$session = new api_session();
$session->connectCredentials($companyID, $userID, $password, $senderId, $senderPassword);
or a current session:
$session = new api_session();
$session->connectSessionId($sessionID, $senderId, $senderPassword);
Alternately, you may need to slide into an entity where you have credentials from a multi-entity organization. In this case, you would use the connectCredentialsEntity method:
$session = new api_session();
$session->connectCredentialsEntity($companyID, $userID, $password, $senderId, $senderPassword, $entityType, $entityId);
With a session in place, you can begin making API requests. Available requests are divided into public methods in the api_post class. Most of these match up with the standard XML requests already documented. Others are combinations that may require explanation:
read($object, $id, $fields, api_session $session)
Same as the XML method
create($records, api_session $session)
Same as the XML method
update($records, api_session $session)
Same as the XML method
upsert($object, $records, $nameField, $keyField, api_session $session, $readOnlyName = false)
If record exists, request updates it. If record does not exist, request creates it.
delete($object, $ids, api_session $session)
Same as the XML method
otherMethod($xml, api_session $session, $dtdVersion="3.0")
Allows you to send XML for 3.0 requests that don’t have a method in the library.
call21Method($function, $phpObj, api_session $session)
Sends the function block for calls that conform to the 2.1 DTD.
sendFunctions($phpObj, api_session $session, $dtdVersion="2.1")
Build an array of functions and send them at the same time.
get_list($object, $filter, $sorts, $fields, api_session $session, $dtdVersion="2.1")
Same as the XML method
call21UpdateMethod($function, $key, $phpObj, api_session $session)
Use as a wrapper for 2.1 update request.
readView($viewName, api_session $session, api_viewFilters $filterObj=null, $maxRecords = self::DEFAULT_MAXRETURN, $returnFormat = api_returnFormat::PHPOBJ)
Same as the XML method. Adding runtime filters requires building the filters with the api_viewFilter and api_viewFilters classes.
readByQuery($object, $query, $fields, api_session $session, $maxRecords=self::DEFAULT_MAXRETURN, $returnFormat=api_returnFormat::PHPOBJ)
Same as the XML method
inspect($object, $detail, api_session $session)
Same as the XML method
readByName($object, $name, $fields, api_session $session)
Same as the XML method
readRelated($object, $keys, $relation, $fields, api_session $session)
Same as the XML method
deleteAll($object, api_session $session, $max=10000)
Repeats the delete method on all records in object up to the set maximum.
deleteByQuery($object, $query, api_session $session, $max=10000)
First finds the records to be deleted using readByQuery, then deletes the records up to the set maximum.
execute($body, $endPoint)
You won't normally use this function, unless you just want to pass a fully constructed XML document to Intacct.
findResponseErrors($response)
Validate the response from Intacct and look for request level errors.
processListResults($response, $returnFormat = api_returnFormat::PHPOBJ)
Process results from any of the get_list method and convert into the appropriate structure.
getLastRequest()
Get the last full XML document passed to Intacct.
getLastResponse()
Get the last response from Intacct.
setDryRun($tf=true)
Set the invocation to generate XML, but not post it to Intacct.
Notes on method parameters: Parameter variables listed as equals (=) value are optional with the listed value being the default. For example, “$max=10000” indicates that the $max variable is optional and if you leave it out, it defaults to 10,000. Parameter variables preceded by a class name require that the value contain an object instance of the class. For example, “api_session $session” indicates that the $session variable is an instance of the api_session class.
An API request is made by calling the method of the request and supplying the necessary parameters. For instance, the following request gets a set of records by reading a view.
$response = api_post::readView($setting['billboard_view'], $session);
The response variable receives an associative array of the record(s) returned by the request. If the number of records exceeds the page size (default 1,000), the readView method automatically performs a readMore until it has added all the records from the list view into the array.
To read a field value, simply call the row by its index and the field name, like this:
$response[0]['sample']
To move through the set of returned records, iterate over the records like so:
for($i = 0;$i < count($response);$i++){
$long_name = $response["$i"]['id'] . '-' . $response["$i"]['sample'];
… // Do other stuff with the data here.
}
You will run into some special cases that require you to write and post XML, such as posting a file.
$xml = '<create> <iph_output> <name>' . $outputName . '</name> <description>' . $outputDescription . '</description> <release>' . $release . '</release> <file_contenttype>text/plain</file_contenttype> <file_filename>' . $filename . '</file_filename> <file>' . base64_encode($lines) . '</file> </iph_output> </create>'; if(!$create = api_post::otherMethod($xml, $session)){ echo 'Cannot post file to output object.'; }
In general though, the library will help you avoid writing XML and also ensure that your requests are properly constructed. It doesn’t hurt that it also returns results in easy-to-navigate arrays.