/ 
WebService-Autotask-1.5
River stage zero No dependents
/ WebService::Autotask

NAME

WebService::Autotask - Interface to the Autotask webservices API.

SYNOPSIS

my $at = WebService::Autotask->new({
  username => 'user@autotask.account.com',
  password => 'some_password'
});

my $list = $at->query({
  entity => 'Account',
  query => [
    {
      name => 'AccountName',
      expressions => [{op => 'BeginsWith', value => 'b'}]
    },
  ]
});

$list->[0]->{AccountName} = 'New Account Name';

$at->update(@$list);

$list = $at->create(
  bless({
    AccountName => "Testing Account Name",
    Phone => "800-555-1234",
    AccountType => 1,
    OwnerResourceID => 123456,
  }, 'Account')
);

DESCRIPTION

"WebService::Autotask" is a module that provides an interface to the Autotask webservices API. Using this method and your Autotask login credentials you can access and manage your Autotask items using this interface. You should read the Autotask API documentation prior to using this module.

Note: all input is assumed to be UTF-8.

CONSTRUCTOR

new

Create a new WebService::Autotask SOAP interface object. This takes a hash references with the following arguments:

username

The username to use when logging into the Autotask system

password

The password to use when logging into the Autotask system.

proxy

If you know which proxy server you are to use then you may supply it here. By default one of the proxies is used and then the correct proxy is determined after logging in. If the default proxy is not correct the correct proxy will then be logged into automatically. This option should not be required.

METHODS

query(%args)

Generic query method to query the Autotask system for entity data. This takes a hash ref as its argument. If an error occurs while trying to parse the given arguments or creating the associated QueryXML query this method will die with an appropriate error. Returns either the single matching entry as a hash reference, or an array of hash references when more than one result is returned. The following keys are allowed:

entity

The name of the entity you want to query for.

query

An array reference of fields and conditions that are used to construct the query XML. See below for the definition of a field and a condition.

field

A field is a hash reference that contains the following entries

name

The name of the field to be querying.

udf

Boolean value to indicate if this field is a user defined field or not. Only one UDF field is allowed per query, by default if ommited this is set to false.

expressions

An array of hash references for the expressions to apply to this field. The keys for this hash refernce are:

op

The operator to use. One of: Equals, NotEqual, GreaterThan, LessThan, GreaterThanOrEquals, LessThanOrEquals, BeginsWith, EndsWith, Contains, IsNull, IsNotNull, IsThisDay, Like, NotLike or SoundsLike. If not in this list an error will be issued.

value

The appropriate value to go with the given operator.

condition

A condition block that allows you define a more complex query. Each condition element is a hash reference with the following fields:

operator

The condition operator to be used. If no operator value is given AND is assumed. Valid operators are: AND and OR.

elements

Each condition contains a list of field and/or expression elements. These have already been defined above.

An example of a valid query woudl be:

 query => [
 	{
 		name => 'AccountName',
 		expressions => [{op => 'Equals', value => 'New Account'}]
	},
	{
		operator => 'OR',
		elements => [
			{
				name => 'FirstName',
				expressions => [
					{op => 'BeginsWith', value => 'A'},
					{op => 'EndsWith', value => 'S'}
				]
			},
			{
				name => 'LastName',
				expressions => [
					{op => 'BeginsWith', value => 'A'},
					{op => 'EndsWith', value => 'S'}
				]
			}
		]
	}
 ]

This will find all accounts with the AccountName of New Account that also have either a FirstName or a LastName that begins with an A and ends with an S.

update(@entities)

Update the given entities. Entites will be verified prior to submitted to verify that they can be updated, any fields that are not updatable will be ignored. Each object reference needs to be blessed with the entity type that it is (Account, Contact, etc). Returns the list of entites that were updated successfully. If an error occurs $@ will be set and undef is returned. See the section on Entity format for more details on how to format entities to be accepted by this method.

create(@entities)

Create the given entities. Entites will be verified prior to submitted to verify that they can be created, any fields that are not creatable will be ignored on creation. Each object reference needs to be blessed with the entity type it is (Account, Contact, etc). Returns the list of entites that were created successfully. If an error occurs $@ will be set and undef is returned. See the section on Entity format for more details on how to format entities to be accepted by this method.

get_picklist_options($entity, $field)

Return a hash that contains the ID values and options for a picklist field item. If the field is not a picklist field then an empty hash will be retruned. The hash is formated with the labels as keys and the values as the values.

create_attachment($attach)

Create a new attachment. Takes a hashref containing Data (the raw data of the attachment) and Info, which contains the AttachmentInfo. Returns the new attachment ID on success.

get_attachment($id)

Fetch an attachment; the only argument is the attachment ID. Returns a hashref of attachment Data and Info, or undef if the specified attachment doesn't exist or if there is an error.

delete_attachment($id)

Delete an attachment; the only argument is the attachment ID. Returns true on success or sets the error string on failure.

ENTITY FORMAT

The follow section details how to format a variable that contains entity informaiton. Entites are required for creating and updating items in the Autotask database.

An entity is a blessed hash reference. It is bless with the name of the type of entity that it is (Account, Contract, Contact, etc). They keys of the hash are the field names found in the Autotask entity object. The values are the corresponding values to be used.

A special key is used for all user defined fields (UserDefinedFields). This entry contains a hash reference containing one key UserDefinedField. This is in turn an array reference containing each user defined field. The user defined field entry looks simliar to this:

{
  UserDefinedField => [
    {
      Name => "UserDefinedField1",
      Value => "Value for Field"
    },
    {
      Name => "SecondUDF",
      Value => "Value for SecondUDF"
    }
  ]
}

When used together the entire structure looks something simliar to this:

bless({
  FieldName1 => "Value for FieldName1",
  Field2 => "Value for Field2",
  UserDefinedFields => {
    UserDefinedField => [
      {
        Name => "UserDefinedField1",
        Value => "Value for Field"
      },
      {
        Name => "SecondUDF",
        Value => "Value for SecondUDF"
      }
    ]
  }
}, 'EntityName')

Obviously the above is just an example. You will need to look at the actual fields that are allowed for each Autotask entity. The user defined fields also will depend on how your instance of Autotask has been configured.

DEPENDENCIES

SOAP::Lite, MIME::Base64

AUTHOR

Derek Wueppelmann (derek@roaringpenguin.com)

Attachment, UTF-8 support added by Chris Adams (cmadams@hiwaay.net)

LICENSE AND COPYRIGHT

Copyright (c) 2010 Roaring Penguin Software, Inc.

Attachment, UTF-8 support Copyright (c) 2013 HiWAAY Information Services, Inc.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Autotask (tm) is a trademark of Autotask.