12. Integria IMS API

External Integria API

Integria's external API is used by making remote calls via HTTP or HTTPS on the file/include/api.php. With this method it's possible to integrate third party applications with Integria. The use of the API is done with a call that includes some predefined parameters, and which returns a value or list of values.

The prototype for the API call is as follows:

http://<instalación Integria>/include/api.php<parametros>

The API only allows the following parameters (other parameters will be ignored):

  • user (mandatory): Integria username that accesses other data. Used for verifying ACLs.
  • user_pass (mandatory): user password.
  • op (mandatory): operation to be done. The operations are detailed below.
  • pass (mandatory if enabled): API password that has been configured in the Integria console.
  • params: list of parameters that will pass on to the function, separated by a token.
  • token: token that separates different parameters (default is a comma).
  • return_type: format for the call results. Can be XML or CSV (although default is CSV).
  • info: special parameter with which the version can be obtained before authentication.

Security

The authentication for Integria's API is done in three steps.

Validated IP authentication

Security is based on a list of IPs that will have access to the tool. This list can be created through Integria's configuration menu.

It's important to keep in mind that this authentication method is always active. If you do not wish to use it, it is necessary to place the character * (all authorized IPs) as the only IP on the list.

Password authentication

In Integria's configuration menu it's possible to establish a password for the API. This password must be sent on the on clear API call, that's why it's recommended to use HTTPS if you want to use this authentication method.

If the password is empty it means that the password authentication is disabled and the token 'pass' is unnecessary in the API call.

Authentication by user and password (login)

Necessary on all calls (except informative calls)to specify the user (user) and user password (user_pass). There's no way to disable this authentication step.

API functions

Information retrieval on Integria IMS

This is a special feature that can be used without authentication since the information returned can be obtained from the login screen, and is not considered a security vulnerability.

Returns the Integria IMS version, and is useful for verifying that on this route there is an Integria IMS installation or to obtain the version before authenticating.

Call

http://127.0.0.1/integria/include/api.php?info=version

Result

Integria IMS OpenEdition v4.0dev - Build 130514 MR5

Instances

get_incidents

  • Result: returns a list of tickets to which the user making the call has access.
  • Serial parameters:
    • String filter: shows only those tickets that contain a certain string in the title or description (non-mandatory). Empty for all tickets. It doesn't distinguish upper or lowercase.
    • Status filter: status ID (non-mandatory). Can adopt the following values:
      • 0 → All (default)
      • 1 → New
      • 2 → Unconfirmed
      • 3 → Assigned
      • 4 → Reopened
      • 5 → Pending to be closed
      • 6 → Pending on a third person
      • 7 → Closed
      • -10 → For all except those closed
    • Group filter: group ID (mandatory). 1 for all.

Call results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incidents&params=day,-10,1

CSV results

5,"2016-01-19 11:19:42","0000-00-00 00:00:00",Titulo incidencia,
admin,1,1,2,"2014-01-19 11:19:42",,1,0,0,,1,0,0,1,0,[email protected],
,0,"2014-01-20 14:45:01",,,,0,0,0,0,0,0,0

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=download_file&params=32&return_type=xml

XML results

<xml version='1.0' encoding='UTF-8'>
  <incident>
     <id_incidencia><![CDATA[5]]></id_incidencia>
     <inicio><![CDATA[2016-01-19 11:19:42]]></inicio>
     <cierre><![CDATA[0000-00-00 00:00:00]]></cierre>
     <titulo><![CDATA[Titulo incidencia]]></titulo>
     <descripcion><![CDATA[Descripcion]]></descripcion>
     <id_usuario><![CDATA[admin]]></id_usuario>
     <estado><![CDATA[1]]></estado>
     <prioridad><![CDATA[1]]></prioridad>
     <id_grupo><![CDATA[2]]></id_grupo>
     <actualizacion><![CDATA[2016-01-19 11:19:42]]></actualizacion>
     <id_creator><![CDATA[]]></id_creator>
     <notify_email><![CDATA[1]]></notify_email>
     <id_task><![CDATA[0]]></id_task>
     <resolution><![CDATA[0]]></resolution>
     <epilog><![CDATA[]]></epilog>
     <id_parent><![CDATA[1]]></id_parent>
     <sla_disabled><![CDATA[0]]></sla_disabled>
     <affected_sla_id><![CDATA[0]]></affected_sla_id>
     <id_incident_type><![CDATA[1]]></id_incident_type>
     <score><![CDATA[0]]></score>
     <email_copy><![CDATA[[email protected]]]></email_copy>
     <editor><![CDATA[]]></editor>
     <id_group_creator><![CDATA[0]]></id_group_creator>
     <last_stat_check><![CDATA[2016-01-20 14:55:01]]></last_stat_check>
     <closed_by><![CDATA[]]></closed_by>
     <extra_data><![CDATA[]]></extra_data>
     <extra_data2><![CDATA[]]></extra_data2>
     <blocked><![CDATA[0]]></blocked>
     <old_status><![CDATA[0]]></old_status>
     <old_resolution><![CDATA[0]]></old_resolution>
     <old_status2><![CDATA[0]]></old_status2>
     <old_resolution2><![CDATA[0]]></old_resolution2>
     <workunits_hours><![CDATA[0]]></workunits_hours>
     <workunits_count><![CDATA[0]]></workunits_count>
  </incident>
</xml>

get_incident_details

  • Result: returns details on a ticket.
  • Parameters:
    • Ticket ID (mandatory).

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incident_details&params=2

CSV Results

1,"2010-02-17 01:35:35","0000-00-00 00:00:00",Myfddfe,,demo,
1,1,3,3,"2010-02-17 01:50:05",user,1,0,0,,,0,0,0,0

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_incident_details&params=2&return_type=xml

XML Results

<xml>
       <id_incidencia>1</id_incidencia>
       <inicio>2010-02-17 01:35:35</inicio>
       <cierre>0000-00-00 00:00:00</cierre>
       <titulo>Myfddfe</titulo>
       <descripcion></descripcion>
       <id_usuario>demo</id_usuario>
       <origen>1</origen>
       <estado>1</estado>
       <prioridad>3</prioridad>
       <id_grupo>3</id_grupo>
       <actualizacion>2010-02-17 01:50:05</actualizacion>
       <id_creator>admin</id_creator>
       <notify_email>1</notify_email>
       <id_task>0</id_task>
       <resolution>0</resolution>
       <epilog></epilog>
       <id_parent></id_parent>
       <sla_disabled>0</sla_disabled>
       <affected_sla_id>0</affected_sla_id>
       <id_incident_type>0</id_incident_type>
       <score>0</score>
</xml>

create_incident

  • Result: a ticket is created.
  • User: the ticket author.
  • Parameters:
    • Title (mandatory). Empty titles are not allowed.
    • Group ID (mandatory).
    • Priority (non-mandatory). Can have the following values:
      • 10 → 0 Maintenance.
      • 0 → 1 Informative (por defecto):
      • 1 → 2 Low.
      • 2 → 3 Medium.
      • 3 → 4 Serious.
      • 4 → 5 Very serious.
    • Description (non-mandatory). Empty by default.
    • Inventory ID (non mandatory).
    • Incident type ID (non mandatory). 0 (none) by default.
    • Email on Carbon Copy (non-mandatory): empty by default.
    • Owner (non-mandatory). Admin by default.
    • Parent ticket ID (non mandatory). 0 by default (no parent)
    • Status (non mandatory). Can adopt the following values:
      • 1 → New (default)
      • 2 → Unconfirmed
      • 3 → Assigned
      • 4 → Reopened
      • 5 → Pending to be closed
      • 6 → Pending on a third person
      • 7 → Closed
    • Info_extra(non mandatory)
    • Solution
      • 0 → None (default)
      • 1 → Fixed
      • 2 → Invalid
      • 3 → Won't fix
      • 4 → Duplicate
      • 5 → Works for me
      • 6 → Incomplete
      • 7 → Expired
      • 8 → Moved
      • 9 → In process
    • Info_extra2 (non mandatory)
    • CampoTipoIncidencia1
    • CampoTipoIncidenciaN

Calls with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=create_incident&params=Titulo%20de%20la%20incidencia,
2,1,Descripcion%20de%20la%incidencia,1,1,[email protected],admin,0,1

CSV result

0

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&pass=
api_pass&op=create_incident&params=Titulo%20de%20la%20incidencia,2,1,
Descripcion%20de%20la%incidencia,1,1,[email protected],admin,0&return_type=xml

XML result

<xml>
   0
</xml>

update_incident

  • Result: updates ticket data.
  • Parameters:
    • ticket ID (mandatory).
    • Title (mandatory). Empty titles are not allowed.
    • Description (non-mandatory). Empty by default.
    • Epilogue (non-mandatory). Empty by default.
    • Group ID (mandatory).
    • Priority (non-mandatory). Can have these values:
      • 10 → 0 Maintenance.
      • 0 → 1 Informative (default):
      • 1 → 2 Low.
      • 2 → 3 Medium.
      • 3 → 4 Serious.
      • 4 → 5 Very serious.
    • Solution
      • 0 → None (default)
      • 1 → Fixed
      • 2 → Invalid
      • 3 → Won't fix
      • 4 → Duplicate
      • 5 → Works for me
      • 6 → Incomplete
      • 7 → Expired
      • 8 → Moved
      • 9 → In process
    • Status (non-mandatory). Can adopt the following values:
      • 1 → New (default)
      • 2 → unconfirmed
      • 3 → Assigned
      • 4 → Reopened
      • 5 → Pending to be closed
      • 6 → Pending on a third person
      • 7 → Closed
    • Owner (non mandatory). Admin by default.
    • Parent ticket ID(non-mandatory). Default 0 (no parent).
    • Instance type ID (non-mandatory). 0 (none)by default.
    • Info_extra (non-mandatory)
    • InstanceTypeField1
    • InstanceTyepFieldN

WARNING: if you do not wish to modify the current value on ticket type field, said fields must be filed with their corresponding worth. If left empty, they'll be uploaded with no value.

Calls with results in CSV formats

http://127.0.0.1/integria/include/api.php?user=user&pass=api_pass&op=
update_incident&params=4,nuevo%20titulo,nueva%20descripcion,
nuevo%20epilogo,4,2,1,3,admin,0,6,,Soporte,Hardware

CSV Result

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&pass=api_pass&op=update_incident
&params=4,nuevo%20titulo,nueva%20descripcion,nuevo%20epilogo,4,2,1,1,3,
admin,0,6,Soporte,Hardware&return_type=xml

XML Result

<xml>
   0
</xml>

delete_incident

  • Result: a ticket is deleted.
  • Parameters:
    • Ticket ID (mandatory)

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user
&pass=api_pass&op=delete_incident&params=3

CSV result

0

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&pass=
api_pass&op=delete_incident&params=3&return_type=xml

XMLresult

<xml>
   0
</xml>

get_incident_workunits

  • Result: returns a list with the WUs associated with a ticket.
  • Parameters:
    • Ticket ID (mandatory).

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user
&user_pass=user_pass&pass=api_pass&op=get_incident_workunits&params=3

CSV Result

3,"2010-02-17 01:48:48",0.25,admin,"Workunit description",0,0,,1
2,"2010-02-17 01:47:41",0.25,admin,"Another workunit description",0,0,,1

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=user_pass&
pass=api_pass&op=get_incident_workunits&params=3&return_type=xml

XML Result

<xml>
        <workunit>
                  <id>3</id>
                  <timestamp>2010-02-17 01:48:48</timestamp>
                  <duration>0.25</duration>
                  <id_user>admin</id_user>
                  <description>Workunit description</description>
                  <have_cost>0</have_cost>
                  <id_profile>0</id_profile>
                  <locked></locked>
                  <public>1</public>
        </workunit>
        <workunit>
                  <id>2</id>
                  <timestamp>2010-02-17 01:47:41</timestamp>
                  <duration>0.25</duration>
                  <id_user>admin</id_user>
                  <description>Another workunit description</description>
                  <have_cost>0</have_cost>
                  <id_profile>0</id_profile>
                  <locked></locked>
                  <public>1</public>
        </workunit>
</xml>

create_workunit

  • Result: creates a workunit on a ticket
  • Parameters:
    • Ticket ID (mandatory).
    • Description (non-mandatory). Empty by default
    • Duration in hours (non-mandatory). Default is 0.00 hours.
    • If there was cost involved (non mandatory). By default the setting is 'no'.
    • If it's public or not (non-mandatory). By default the setting is 'no'.
    • Associated profile ID (non mandatory). By default it's 0 (no associated profile).

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_workunit&params=1,Descripcion,0.5,0,1,1

CSV Result

0

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_workunit&params=1,Descripcion,0.5,0,1,1&return_type=xml

XML Result

<xml>
   0
</xml>

get_incident_files

  • Result: returns a list with files associated to a ticket
  • Parameters:
    • Ticket ID (mandatory)

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass=
&pass=api_pass&op=get_incident_files&params=1

CSV Result

1,1,0,0,admin,file1.php,"php example",764026
2,1,0,0,admin,file2.png,"png example",34026

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass=
&pass=api_pass&op=get_incident_files&params=1&return_type=xml

XML Result

<xml>
   <file>
       <id_attachment>1</id_attachment>
       <id_incidencia>1</id_incidencia>
             <id_task>0</id_task>
             <id_kb>0</id_kb>
             <id_usuario>admin</id_usuario>
             <filename>file1.php</filename>
             <description>php example</description>
             <size>764026</size>
   </file>
   <file>
     <id_attachment>2</id_attachment>
     <id_incidencia>1</id_incidencia>
             <id_task>0</id_task>
             <id_kb>0</id_kb>
             <id_usuario>admin</id_usuario>
             <filename>file2.png</filename>
             <description>png example</description>
             <size>34026</size>
   </file>
</xml>

download_file

  • Result: retrieves the content of a file in text, on base64.
  • Parameters:
    • File ID (mandatory)

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=download_file&params=32

CSV Result

[file content on base64]

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incidents&params=day,-10,1&return_type=xml

XML Result

<xml>
   [file content on base64]
</xml>

attach_file

  • Result: adds a file to the list of ticket files
  • Parameters:
    • Ticket ID: (non mandatory) 0 by default.
    • File name: (non mandatory).
    • File size in bytes: (non mandatory) 0 by default.
    • File description: (non mandatory) empty by default.
    • File content on base 64 (non mandatory) by default created with no content.

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=attach_file&params=1,example.txt,234,Fichero
%20de%20ejemplo,aW50ZWdyaWEgcm9ja3M=

CSV result

0

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=attach_file&params=1,example.txt,234,Fichero
%20de%20ejemplo,aW50ZWdyaWEgcm9ja3M=&return_type=xml

XML result

<xml>
   0
</xml>

delete_file

  • Result: deletes a file from a ticket's file list
  • Parameters:
    • File ID (mandatory)

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=delete_file&params=32

CSV result

0

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=delete_file&params=32&return_type=xml

XML result

<xml>
   0
</xml>

create_user

Call used to create a user and assign it to a role/group. To assign more profiles a different call must be used.

  • Result: returns a value of 1 if performed correctly, otherwise returns 0.
  • Parameters:
    • Username: (mandatory)
    • Group ID: (mandatory)
    • Profile ID: (mandatory)
    • Email: (non-mandatory). Empty by default
    • Password: (non-mandatory). By default it's the username
    • Description: (non-mandatory). Empty by default
    • Real name: (non-mandatory). Empty by default.
    • Externaluser: (non-mandatory). 0 by default.

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_user&params=jorge,3,4,[email protected],
userpass,description,Jorge%20Apellido,1

CSV result

1

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=api_pass&
op=create_user&params=jorge,3,4,[email protected],userpass,description,
Jorge%20Apellido,1&return_type=xml

XML result

<xml>
   1
</xml>

validate_user

  • Result: returns 1 if the authentication is correct, otherwise value is 0.
  • Parameters:
    • User: username of the user we want to validate (mandatory).
    • Pass: password for the user (mandatory).

Calls with results in CSV format

http://127.0.0.1/integria/include/api.php?&user=user&user_pass=
userpass&pass=api_pass&op=validate_user&params=jorge,jorge_pass

CSV Result

1

Calls with results in XML format

http://127.0.0.1/integria/include/api.php?&user=user&user_pass=
userpass&pass=api_pass&op=validate_user&params=jorge,jorge_pass
&return_type=xml

XML result

<xml>
   1
</xml>

delete_user

Call used to delete an user. Admin profiles can't be deleted using the API.

  • Returns: 1 if deleted correctly, 0 otherwise.
  • Parameters
    • User: (mandatory)

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=delete_user&params=pepe

CSV result

1

Calls with result in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=delete_user&params=pepe&return_type=xml

XML result

<xml>
   1
</xml>

user_exists

Call used to confirm that an user exists.

  • Result: returns 1 if it exists, 0 otherwise.
  • Parameters
    • User: (mandatory)

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=user_exists&params=pepe

CSV result

1

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=user_exists&params=pepe&return_type=xml

XML result

<xml>
   1
</xml>

create_lead

Call used to create a lead.

  • Result: returns 1 if correctly created, 0 otherwise.
  • Parameters:
    • Full name: (mandatory)
    • Company: (mandatory)
    • Email (mandatory)
    • Country: (non-mandatory) Empty by default.
    • Estimated sales: (non-mandatory) 0 by default.
    • Progress: measured in percentage (non-mandatory). Default is 0%
    • Telephone: (non-mandatory). Empty by default.
    • Cellphone: (non-mandatory). Empty by default
    • Position: (non-mandatory). Empty by default.
    • Owner: username (mandatory).
    • Language: language coding (mandatory).
      • de → Deustch
      • en_GB → English
      • es → Español
      • fr → Français
      • pl → Polski
      • ru → Русский
      • zh_CN → 简化字
    • Commentaries: (non-mandatory). Empty by default.
    • Category ID: (non-mandatory). Default is 0 (none).
    • Directed by: (non-mandatory). Default is 0.
    • Campaign: (non-mandatory). Default is 0.
    • Tag separator: (mandatory if multiple tags are going to be added).
    • Tag names: divided with the separator configured above. If the tags do not exist, they will not be stored.

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_lead&params=Dario%Rodriguez%Perez,Artica+ST,
[email protected],Spain,230,0,55566677,6665577,Developer,admin,es,
This%20comment%20is%20very%20important,1,0,7,-%7C-,Software-%7C-
Hardware-%7C-Tag%20con%20espacios

CSV result

1

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_lead&params=Dario%Rodriguez%Perez,Artica+ST,
[email protected],Spain,230,0,55566677,6665577,Developer,admin,es,This%20comment
%20is%20very%20important,1,0,7,-%7C-,Software-%7C-Hardware-%7C-
Tag%20con%20espacios&return_type=xml

XML result

<xml>
   1
</xml>

get_last_invoice_id

Call used to obtain the latest invoice ID.

  • Result: returns the last invoice ID, empty otherwise.
  • Parameters: -

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_last_invoice_id

CSV result

140601_0082

Call with result in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_last_invoice_id&return_type=xml

XML result

<xml>
 <last_invoice_id>
  <id><![CDATA[140601_0082]]></id>
 </last_invoice_id>
</xml>

get_invoice

Call to obtain invoice information.

  • Returns: invoice information, left empty if none is available.
  • Parameters:
    • Invoice ID: the value for the Invoice ID field (mandatory).

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_invoice&params=140601_0071

CSV result

2,admin,,1,140601_0071,ads,,,,,222.00,0.00,0.00,0.00,0.00,0.00,
EUR,,0,0,,2014-01-24,0000-00-00,pending,,,Submitted,en_GB

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_invoice&params=140601_0071&return_type=xml

XML result

<xml>
 <invoice>
  <id><![CDATA[2]]></id>
  <id_user><![CDATA[admin]]></id_user>
  <id_task><![CDATA[]]></id_task>
  <id_company><![CDATA[1]]></id_company>
  <bill_id><![CDATA[140601_0071]]></bill_id>
  <concept1><![CDATA[ads]]></concept1>
  <concept2><![CDATA[]]></concept2>
  <concept3><![CDATA[]]></concept3>
  <concept4><![CDATA[]]></concept4>
  <concept5><![CDATA[]]></concept5>
  <amount1><![CDATA[222.00]]></amount1>
  <amount2><![CDATA[0.00]]></amount2>
  <amount3><![CDATA[0.00]]></amount3>
  <amount4><![CDATA[0.00]]></amount4>
  <amount5><![CDATA[0.00]]></amount5>
  <tax><![CDATA[0.00]]></tax>
  <currency><![CDATA[EUR]]></currency>
  <description><![CDATA[]]></description>
  <id_attachment><![CDATA[0]]></id_attachment>
  <locked><![CDATA[0]]></locked>
  <locked_id_user><![CDATA[]]></locked_id_user>
  <invoice_create_date><![CDATA[2014-01-24]]></invoice_create_date>
  <invoice_payment_date><![CDATA[0000-00-00]]></invoice_payment_date>
  <status><![CDATA[pending]]></status>
  <reference><![CDATA[]]></reference>
  <internal_note><![CDATA[]]></internal_note>
  <invoice_type><![CDATA[Submitted]]></invoice_type>
  <id_language><![CDATA[en_GB]]></id_language>
 </invoice>
</xml>

create_invoice

Call to create invoice.

  • Result: returns two values, the status code (1 if the operation was performed, 0 if an error was detected) and a message with the operation results.
  • Parameters:
    • User ID: (must exist or be left empty)
    • Task ID: (non-mandatory). By default it's 0.
    • Company ID: (mandatory).
    • Invoice ID: (mandatory).
    • Concept: (mandatory).
    • Quantity: (mandatory).
    • Taxes: tax percentage applicable (non-mandatory). 0 by default.
    • Currency: text string (mandatory).
    • Description: (non-mandatory). Empty by default.
    • Blocked flag: Boolean (non-mandatory). 0 by default (unblocked).
    • Blocking user ID: (mandatory if blocked flag is enabled). Empty by default.
    • Creation date: (non-mandatory). Current day by default.
    • Payment day: (non-mandatory). Default is current day.
    • Status (non-mandatory). Default is pending
    • Reference (non-mandatory). Default is empty.
    • Internal note (non-mandatory). Default is empty.
    • Invoice type (mandatory: submitted or received statuses).
    • Language ID: (non-mandatory).
      • de → Deutch
      • en_GB → English (default setting)
      • es → Español
      • fr → Français
      • pl → Polski
      • ru → Русский
      • zh_CN → 简化字

Error-free call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&pass=1234&op=create_invoice&params=admin,,1,140601_0082,paso,3.00,
,EUR,,,,,,paid,,,Submitted,

Error-free CSV result

1,"invoice created"

CSV result with errors

0,"invalid billing ID"

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_invoice&params=admin,,1,140601_0082,paso,3.00,,EUR,
,,,,,paid,,,Submitted,&return_type=xml

Error-free XML result

<xml>
 <invoice>
  <status><![CDATA[1]]></status>
  <error><![CDATA[invoice created]]></error>
 </invoice>
</xml>

Resultado XML con errores

<xml>
 <invoice>
  <status><![CDATA[0]]></status>
  <error><![CDATA[invalid billing id]]></error>
 </invoice>
</xml>

create_company

  • Result: returns the ID for the created company
  • Parameters:
    • Name: (mandatory)
    • Address: (non-mandatory). Empty by default.
    • Fiscal ID: (non-mandatory). Empty by default.
    • Company role ID: (non-mandatory). Default is 0 (no role).
    • Country: (non-mandatory). Empty by default.
    • Manager: usernam in charge of the company (must exist or be left empty).
    • Parent company ID: (unnecessary). Default is 0.

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_company&params=Artica,AlbertoAguilera,12312312,1,Pais,admin,0

CSV result

6

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=create_company&params=Artica,AlbertoAguilera,12312312,1,
Pais,admin,0&return_type=xml

XML result

<xml>
 <company>
  <id><![CDATA[6]]></id>
 </company>
</xml>

add_address_to_newsletter

  • Result: retrieves the ID for the email address created. If it fails, 0 is returned.
  • Parameters:
    • Newsletter ID: (is mandatory and must exist)
    • Name: (mandatory).
    • Email: (mandatory).

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
integria&op=add_address_to_newsletter&params=2,juan,[email protected]

CSV result

10

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
integria&op=add_address_to_newsletter&params=2,juan,[email protected]&return_type=xml

XML result

<xml>
   10
</xml>

get_incident_tracking

  • Result: retrieves a list with a ticket's tracking
  • Parameters:
    • Ticket ID (mandatory).

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_incident_tracking&params=2

CSV result

9,2,0,"2010-02-17 01:56:33",demo,0,Created
10,2,2,"2010-02-17 02:06:58",demo,0,"Workunit added"

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_incident_tracking&params=2&return_type=xml

XML result

<xml>
   <tracking>
               <id_it>9</id_it>
               <id_incident>2</id_incident>
               <state>0</state>
               <timestamp>2010-02-17 01:56:33</timestamp>
               <id_user>demo</id_user>
               <id_aditional>0</id_aditional>
               <description>Created</description>
   </tracking>
   <tracking>
               <id_it>10</id_it>
               <id_incident>2</id_incident>
               <state>2</state>
               <timestamp>2010-02-17 02:06:58</timestamp>
               <id_user>demo</id_user>
               <id_aditional>0</id_aditional>
               <description>Workunit added</description>
   </tracking>
</xml>

get_incidents_resolutions

  • Result: retrieves a list with the IDs and names for ticket solutions on Integria.
  • Parameters: -

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incidents_resolutions

CSV result

1,Fixed
2,Invalid
3,"Wont fix"

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incidents_resolutions&return_type=xml

XML result

<xml>
       <resolution>
               <id>1</id>
               <name>Fixed</name>
       </resolution>
       <resolution>
               <id>2</id>
               <name>Invalid</name>
       </resolution>
       <resolution>
               <id>3</id>
               <name>Wont fix</name>
       </resolution>
</xml>

get_incidents_status

  • Result: retrieves a list with the names and IDs for ticket statuses on Integria
  • Parameters: -

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_incidents_status

CSV result

1,New
2,Unconfirmed
3,Assigned

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_incidents_status&return_type=xml

XML result

<xml>
       <status>
               <id>1</id>
               <name>New</name>
       </status>
       <status>
               <id>2</id>
               <name>Unconfirmed</name>
       </status>
       <status>
               <id>3</id>
               <name>Assigned</name>
       </status>
</xml>

get_groups

  • Result: retrieves a list with the IDs and names for Integria groups.
  • Parameters: -

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_groups

CSV result

2,"Customer #A"
3,"Customer #B"
4,Engineering

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_groups&return_type=xml

XML result

<xml>
       <group>
               <id>1</id>
               <name>"Customer #A"</name>
       </group>
       <group>
               <id>2</id>
               <name>"Customer #B"</name>
       </group>
       <group>
               <id>3</id>
               <name>Engineering</name>
       </group>
</xml>

get_users

  • Result: retrieves a list with the users that the user who made the call can view
  • Parameters: -

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_users

CSV result

usuario1
usuario2
usuario3

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_incidents&params=day,-10,1&return_type=xml

XML result

<xml>
   <id_user>usuario1</id_user>
   <id_user>usuario2</id_user>
   <id_user>usuario3</id_user>
</xml>

get_stats

  • Result: retrieves a value according to the query performed.
  • Parameters: expect the following parameters: metric, string, status, id_user, id_group, id_company, id_product and id_inventory.
    • metric: statistic value metric. Can be one of the following:
      • total_incidents: total number of tickets (limited by the max number of tickets defined on Integria).
      • opened: total number of open tickets.
      • closed: total number of closed tickets.
      • avg_life: average ticket lifespan in seconds.
      • sla_compliance: percentage of SLA compliance.
      • avg_scoring: average grade for tickets from 0-10.
      • avg_worktime: average work time for a ticket in seconds.
    • string: string meant to filter ticket searching
    • status: string with values separated by commas. Can adopt values between 1 and 7. (Default setting is 1,2,3,4,5,6,7)
    • id_user: filtered by user (default “”).
    • id_group: filtered by group (default 1).
    • id_company: filtered by company (default 0).
    • id_inventory: filtered by inventory (default 0).
    • priority: string woth values separated by commas. Can adopt the values 0, 1, 2, 3, 4 and 10. (Default setting is all)

Call with results in CSV format

Obtain SLA %

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_stats&params=sla_compliance

Obtain total number of open tickets with NEW status (code 1), in any group:

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_stats&params=opened,,1

Obtain the total of open tickets (with any status, in any group)

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_stats&params=opened

CSV Results

1,"Sample inventory object"
2,"Another inventory"
3,Third inventory

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=userpass&pass=
api_pass&op=get_stats&params=sla_compliance&return_type=xml

XML results

<xml>
   97
</xml>

get_inventories

  • Result: retrieves a list with the names and IDs for Integria inventories.
  • Parameters: -

Call with results in CSV format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_inventories

CSV result

1,"Sample inventory object"
2,"Another inventory"
3,Thirdventory

Calls with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_inventories&return_type=xml

XML result

<xml>
   <inventory>
       <id>1</id>
       <name>Sample inventory object</name>
   </inventory>
   <inventory>
       <id>2</id>
       <name>Another inventory</name>
   </inventory>
   <inventory>
       <id>3</id>
       <name>Thirdventory</name>
   </inventory>
</xml>

get_last_cron_execution

  • Result: retrieves the time passed (in minutes) from Crontask's last execution.
  • Parameters: -

Call

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_last_cron_execution

Result

3

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_last_cron_execution&return_type=xml

XML result

<xml>
   <cronjob>
               <last_exec>3</last_exec>
   </cronjob>
</xml>

get_num_queued_emails

  • Result: retrieves the number of emails in the queue and pending on delivery.
  • Parameters: -

Call

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_num_queued_emails

Result

20

Call with results in XML format

http://127.0.0.1/integria/include/api.php?user=user&user_pass=
userpass&pass=api_pass&op=get_num_queued_emails&return_type=xml

XML result

<xml>
   <pending_email>
               <num>20</num>
   </pending_email>
</xml>

API extension

To develop new calls for the API, you must bear in mind that:

  • The call has to be signed in as function on the file <instalación Integria>/include/functions_api.php, apart from being contemplated among the valid functions in the file <instalación Integria>/include/api.php.
  • The function must retrieve a single value or an array of couples, for example name-value.
  • The format of results for a call to XML or CSV is performed on the file api.php automatically.

Examples of functions for the API

Example of a function that retrieves a single value

Defined in the file functions_api.php:

function host_risk ($host_name) {
   
   $host_id = get_hosts_id($host_name);

   //If there is not a host with this name return false
   if (!$host_id) {
       return false;
   }
   
   $risk = return_last_risk_agent($host_id);   
   
   return $risk;
}

Call on the file api.php:

switch ($op) {

       ...
    
   case "host_risk":
       if (isset($params['0'])) {
           $result = host_risk ($params['0']);
       } else {
           $result = false;
       }
       break;

      ...
}

Example of a function that retrieves a list of values

Defined in the file functions_api.php:

function all_host_risk() {
   
   //Get all host  
   $hosts = get_hosts();

   //Check if there is host or not
   if (empty($hosts)) {
       return false;
   }
   
   $result = array();
   foreach ($hosts as $host) {
       $host_name = get_host_name($host['id']);
       $risk = return_last_risk_agent($host['id']);     
       
       $aux = array();
       
       $aux['name'] = $host_name;
       $aux['data'] = $risk;

       array_push($result, $aux);
   }
   
   return $result;
} 

Call on the file api.php:

switch ($op) {

       ...

   case "all_host_risk":
       $result = all_host_risk ();
       break;

       ...

 }
 

Integria Documentation