api_ddsJob.php

<?php
/**
 * Copyright (c) 2014, Intacct OpenSource Initiative
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without modification, are permitted provided that the
 * following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
 * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
 * disclaimer in the documentation and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 *
 * OVERVIEW
 * The general pattern for using this SDK is to first create an instance of api_session and call either
 * connectCredentials or connectSessionId to start an active session with the Intacct Web Services gateway.
 * You will then pass the api_session as an argument in the api_post class methods.  intacctws-php handles all
 * XML serialization and de-serialization and HTTPS transport.
 */

/**
 * Class api_ddsJob
 */
class api_ddsJob
{

    /**
     * @var int Internal key of the DDS job (standard object)
     */
    protected $key;

    /**
     * @var string Unique name of the DDS job
     */
    protected $ddsJob;

    /**
     * @var string the source Object's integration name
     */
    protected $object;

    /**
     * @var string Job Type.  One of "All" or "Changed"
     */
    protected $jobType;

    /**
     * @var int Key to the subscription that spawned this job.  Optional
     */
    protected $subscriptionKey;

    /**
     * @var bool|null|string DateTime when the job was queued
     */
    protected $queueTime;

    /**
     * @var bool|null|string DateTime when the job was started
     */
    protected $startTime;

    /**
     * @var bool|null|string DateTime when the job ended
     */
    protected $endTime;

    /**
     * @var int Number of newly created records found by the job
     */
    protected $created;

    /**
     * @var int Number of updated records found by the job
     */
    protected $updated;

    /**
     * @var int Number of deleted records found by the job
     */
    protected $deleted;

    /**
     * @var string Job status.
     */
    protected $status;

    /**
     * @var string Any errors generated by the job
     */
    protected $error;

    /**
     * @var array Set of files delivered by the job
     */
    protected $fileList;

    const DDS_STATUS_COMPLETED = 'Completed';
    const DDS_STATUS_FAILED = 'Failed';
    const DDS_STATUS_QUEUED = 'Queued';
    const DDS_STATUS_PROCESSING = 'Processing';

    /**
     * Construct an instance of a ddsJob record
     *
     * @param simpleXmlElement $ddsJob XML response from Intacct API
     *
     * @throws Exception
     */
    public function __construct(simpleXmlElement $ddsJob)
    {
        $this->key = (int)$ddsJob->RECORDNO;
        $this->ddsJob = (string)$ddsJob->DDSJOB;
        $this->object = (string)$ddsJob->OBJECT;

        $jobType = (string)$ddsJob->JOBTYPE;
        if ($jobType !== null && $jobType != '') {
            if ($jobType != api_post::DDS_JOBTYPE_ALL && $jobType != api_post::DDS_JOBTYPE_CHANGE) {
                throw new Exception("Unexpected DDS JobType $jobType.");
            } else {
                $this->jobType = $jobType;
            }
        }

        $this->subscriptionKey = (string)$ddsJob->SUBSCRIPTIONKEY;
        $this->queueTime = $this->validDateTime((string)$ddsJob->QUEUETIME);
        $this->startTime = $this->validDateTime((string)$ddsJob->STARTTIME);
        $this->endTime = $this->validDateTime((string)$ddsJob->ENDTIME);
        $this->created = (int)$ddsJob->RECORDSCREATED;
        $this->updated = (int)$ddsJob->RECORDSUPDATED;
        $this->deleted = (int)$ddsJob->RECORDSDELETED;

        $validStates = array(
            self::DDS_STATUS_COMPLETED,
            self::DDS_STATUS_FAILED,
            self::DDS_STATUS_PROCESSING,
            self::DDS_STATUS_QUEUED
        );
        if (!in_array((string)$ddsJob->STATUS, $validStates)) {
            throw new Exception("Invalid status " . (string)$ddsJob->STATUS);
        } else {
            $this->status = (string)$ddsJob->STATUS;
        }

        $this->error = (string)$ddsJob->ERROR;
        if ((string)$ddsJob->FILELIST !== '') {
            $this->fileList = explode(',', (string)$ddsJob->FILELIST);
        }

    }

    /**
     * Convert object into array usable by Intacct API
     *
     * @return array
     */
    public function toApiArray()
    {
        $ddsJobAry = array(
            'dds_job' => array(
                'key' => $this->getKey(),
                'name' => $this->getDdsJob(),
                '__object' => $this->getObject(),
                'job_type' => $this->getJobType(),
                'error' => $this->getError(),
                'records_created' => $this->getCreated(),
                'records_deleted' => $this->getDeleted(),
                'records_updated' => $this->getUpdated(),
                'status' => $this->getStatus()
            )
        );

        if ($this->getQueueTime() !== null && $this->getQueueTime() != '') {
            $ddsJobAry['dds_job']['queue_time'] = $this->getQueueTime();
        }

        if ($this->getStartTime() !== null && $this->getStartTime() != '') {
            $ddsJobAry['dds_job']['start_time'] = $this->getStartTime();
        }

        if ($this->getEndTime() !== null && $this->getEndTime() != '') {
            $ddsJobAry['dds_job']['end_time'] = $this->getEndTime();
        }

        return $ddsJobAry;
    }

    /**
     * Return the files list in an array usable by the Intacct API
     *
     * @return array
     */
    public function toApiArrayFiles()
    {

        $filesAry = array();
        $fileList = $this->getFileList();

        foreach ($fileList as $file) {
            $filesAry[] = array(
                'dds_file' => array(
                    'name' => $file,
                    '__dds_job' => $this->getDdsJob()
                )
            );
        }

        return $filesAry;
    }

    /**
     * Validate the dateTime value and throw an exception if invalid, return null if not set
     * or return a valid ISO8601 dateTime value if set and valid
     *
     * @param string $dateTime Date Time value.  This method will attempt to convert from arbitrary formats
     *
     * @return bool|null|string
     * @throws Exception
     */
    private function validDateTime($dateTime)
    {

        if ($dateTime === null || $dateTime == '') {
            return null;
        }

        if (strtotime($dateTime === false)) {
            throw new Exception("Invalid DateTime $dateTime");
        }

        return date("c", strtotime($dateTime));
    }

    /**
     * @return mixed
     */
    public function getId()
    {
        return $this->id;
    }

    /**
     * @return mixed
     */
    public function getCreated()
    {
        return $this->created;
    }

    /**
     * @return mixed
     */
    public function getDdsJob()
    {
        return $this->ddsJob;
    }

    /**
     * @return mixed
     */
    public function getDeleted()
    {
        return $this->deleted;
    }

    /**
     * @return mixed
     */
    public function getEndTime()
    {
        return $this->endTime;
    }

    /**
     * @return mixed
     */
    public function getError()
    {
        return $this->error;
    }

    /**
     * @return mixed
     */
    public function getFileList()
    {
        return $this->fileList;
    }

    /**
     * @return mixed
     */
    public function getJobType()
    {
        return $this->jobType;
    }

    /**
     * @return mixed
     */
    public function getKey()
    {
        return $this->key;
    }

    /**
     * @return mixed
     */
    public function getObject()
    {
        return $this->object;
    }

    /**
     * @return mixed
     */
    public function getQueueTime()
    {
        return $this->queueTime;
    }

    /**
     * @return mixed
     */
    public function getStartTime()
    {
        return $this->startTime;
    }

    /**
     * @return mixed
     */
    public function getStatus()
    {
        return $this->status;
    }

    /**
     * @return mixed
     */
    public function getSubscriptionKey()
    {
        return $this->subscriptionKey;
    }

    /**
     * @return mixed
     */
    public function getUpdated()
    {
        return $this->updated;
    }

}