Module xero.projects
ballerinax/xero.projects Ballerina library
1.5.2
Overview
The Xero Projects API v2.16.0 connector(https://developer.xero.com/documentation/api/projects/overview) OpenAPI specification. The Xero Projects API is a collection of endpoints which businesses to track time and costs on projects/jobs and report on profitability.
Key Features
- Programmatic access to create and manage resources via REST API
- Access analytics, reports, and performance metrics
- Manage user accounts and profiles
- Secure authentication with API key or OAuth support
Prerequisites
Before using this connector in your Ballerina application, complete the following:
- Create a Xero account
- Obtain tokens by following this guide
Clients
xero.projects: Client
Isolated
This is a generated connector for Xero Projects API v2.16.0 OpenAPI specification. The Xero Projects API is a collection of endpoints which businesses to track time and costs on projects/jobs and report on profitability.
Constructor
Gets invoked to initialize the connector.
The connector initialization requires setting the API credentials.
Create a Xero account and obtain tokens by following this guide.
init (ConnectionConfig config, string serviceUrl)- config ConnectionConfig - The configurations to be used when initializing the
connector
- serviceUrl string "https://api.xero.com/projects.xro/2.0" - URL of the target service
getProjects
Isolated FunctionRemote Function
function getProjects(string xeroTenantId, string[]? projectIds, string? contactID, string? states, int page, int pageSize) returns Projects|errorRetrieves all projects
Parameters
- xeroTenantId string - Xero identifier for Tenant
- projectIds string[]? (default ()) - Search for all projects that match a comma separated list of projectIds
- contactID string? (default ()) - Filter for projects for a specific contact
- states string? (default ()) - Filter for projects in a particular state (INPROGRESS or CLOSED)
- page int (default 1) - set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0.
- pageSize int (default 50) - Optional, it is set to 50 by default. The number of items to return per page in a paged response - Must be a number between 1 and 500.
createProject
Isolated FunctionRemote Function
function createProject(string xeroTenantId, ProjectCreateOrUpdate payload) returns Project|errorCreate one or more new projects
Parameters
- xeroTenantId string - Xero identifier for Tenant
- payload ProjectCreateOrUpdate - Create a new project with ProjectCreateOrUpdate object
getProject
Isolated FunctionRemote Function
Retrieves a single project
Parameters
- xeroTenantId string - Xero identifier for Tenant
- projectId string - You can specify an individual project by appending the projectId to the endpoint
updateProject
Isolated FunctionRemote Function
function updateProject(string xeroTenantId, string projectId, ProjectCreateOrUpdate payload) returns Response|errorUpdates a specific project
Parameters
- xeroTenantId string - Xero identifier for Tenant
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- payload ProjectCreateOrUpdate - Request of type ProjectCreateOrUpdate
patchProject
Isolated FunctionRemote Function
function patchProject(string xeroTenantId, string projectId, ProjectPatch payload) returns Response|errorcreates a project for the specified contact
Parameters
- xeroTenantId string - Xero identifier for Tenant
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- payload ProjectPatch - Update the status of an existing Project
getProjectUsers
Isolated FunctionRemote Function
function getProjectUsers(string xeroTenantId, int page, int pageSize) returns ProjectUsers|errorRetrieves a list of all project users
Parameters
- xeroTenantId string - Xero identifier for Tenant
- page int (default 1) - set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0.
- pageSize int (default 50) - Optional, it is set to 50 by default. The number of items to return per page in a paged response - Must be a number between 1 and 500.
Return Type
- ProjectUsers|error - OK/success, returns a list of project objects
getTasks
Isolated FunctionRemote Function
function getTasks(string xeroTenantId, string projectId, int? page, int? pageSize, string? taskIds, ChargeType? chargeType) returns Tasks|errorRetrieves all project tasks
Parameters
- xeroTenantId string - Xero identifier for Tenant
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- page int? (default ()) - Set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0.
- pageSize int? (default ()) - Optional, it is set to 50 by default. The number of items to return per page in a paged response - Must be a number between 1 and 500.
- taskIds string? (default ()) - taskIds Search for all tasks that match a comma separated list of taskIds, i.e. GET https://.../tasks?taskIds={taskID},{taskID}
- chargeType ChargeType? (default ()) - Can be
TIME,FIXEDorNON_CHARGEABLE, defines how the task will be charged. UseTIMEwhen you want to charge per hour andFIXEDto charge as a fixed amount. If the task will not be charged useNON_CHARGEABLE.
getTask
Isolated FunctionRemote Function
Retrieves a single project task
Parameters
- xeroTenantId string - Xero identifier for Tenant
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- taskId string - You can specify an individual task by appending the taskId to the endpoint, i.e. GET https://.../tasks/{taskID}
getTimeEntries
Isolated FunctionRemote Function
function getTimeEntries(string xeroTenantId, string projectId, string? userId, string? taskId, string? invoiceId, string? contactId, int? page, int? pageSize, string[]? states, boolean? isChargeable, string? dateAfterUtc, string? dateBeforeUtc) returns TimeEntries|errorRetrieves all time entries associated with a specific project
Parameters
- xeroTenantId string - Xero identifier for Tenant
- projectId string - Identifier of the project, that the task (which the time entry is logged against) belongs to.
- userId string? (default ()) - The xero user identifier of the person who logged time.
- taskId string? (default ()) - Identifier of the task that time entry is logged against.
- invoiceId string? (default ()) - Finds all time entries for this invoice.
- contactId string? (default ()) - Finds all time entries for this contact identifier.
- page int? (default ()) - Set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0.
- pageSize int? (default ()) - Optional, it is set to 50 by default. The number of items to return per page in a paged response - Must be a number between 1 and 500.
- states string[]? (default ()) - Comma-separated list of states to find. Will find all time entries that are in the status of whatever is specified.
- isChargeable boolean? (default ()) - Finds all time entries which relate to tasks with the charge type 'TIME' or 'FIXED'.
- dateAfterUtc string? (default ()) - ISO 8601 UTC date. Finds all time entries on or after this date filtered on the
dateUtcfield.
- dateBeforeUtc string? (default ()) - ISO 8601 UTC date. Finds all time entries on or before this date filtered on the
dateUtcfield.
Return Type
- TimeEntries|error - OK/success, returns a list of time entry objects
createTimeEntry
Isolated FunctionRemote Function
function createTimeEntry(string xeroTenantId, string projectId, TimeEntryCreateOrUpdate payload) returns TimeEntry|errorCreates a time entry for a specific project
Parameters
- xeroTenantId string - Xero identifier for Tenant
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- payload TimeEntryCreateOrUpdate - The time entry object you are creating
getTimeEntry
Isolated FunctionRemote Function
function getTimeEntry(string xeroTenantId, string projectId, string timeEntryId) returns TimeEntry|errorRetrieves a single time entry for a specific project
Parameters
- xeroTenantId string - Xero identifier for Tenant
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- timeEntryId string - You can specify an individual time entry by appending the id to the endpoint
updateTimeEntry
Isolated FunctionRemote Function
function updateTimeEntry(string xeroTenantId, string projectId, string timeEntryId, TimeEntryCreateOrUpdate payload) returns Response|errorUpdates a time entry for a specific project
Parameters
- xeroTenantId string - Xero identifier for Tenant
- projectId string - You can specify an individual project by appending the projectId to the endpoint
- timeEntryId string - You can specify an individual time entry by appending the id to the endpoint
- payload TimeEntryCreateOrUpdate - The time entry object you are updating
deleteTimeEntry
Isolated FunctionRemote Function
function deleteTimeEntry(string xeroTenantId, string projectId, string timeEntryId) returns Response|errorDeletes a time entry for a specific project
Records
xero.projects: Amount
Fields
- currency? CurrencyCode - 3 letter alpha code for the ISO-4217 currency code, e.g. USD, AUD.
- value? decimal -
xero.projects: ClientHttp1Settings
Closed record
Provides settings related to HTTP/1.x protocol.
Fields
- keepAlive KeepAlive(default http:KEEPALIVE_AUTO) - Specifies whether to reuse a connection for multiple requests
- chunking Chunking(default http:CHUNKING_AUTO) - The chunking behaviour of the request
- proxy? ProxyConfig - Proxy server related options
xero.projects: ConnectionConfig
Closed record
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- auth BearerTokenConfig|OAuth2RefreshTokenGrantConfig - Configurations related to client authentication
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings? ClientHttp1Settings - Configurations related to HTTP/1.x protocol
- http2Settings? ClientHttp2Settings - Configurations related to HTTP/2 protocol
- timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded/x-forwardedheader
- poolConfig? PoolConfiguration - Configurations associated with request pooling
- cache? CacheConfig - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding) header
- circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig? RetryConfig - Configurations associated with retrying
- responseLimits? ResponseLimitConfigs - Configurations associated with inbound response size limits
- secureSocket? ClientSecureSocket - SSL/TLS-related options
- proxy? ProxyConfig - Proxy server related options
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
xero.projects: Error
Fields
- message? string - Exception message
- modelState? record {} - Array of Elements of validation Errors
xero.projects: OAuth2RefreshTokenGrantConfig
Closed record
OAuth2 Refresh Token Grant Configs
Fields
- Fields Included from *OAuth2RefreshTokenGrantConfig
- refreshUrl string(default "https://identity.xero.com/connect/token") - Refresh URL
xero.projects: Pagination
Fields
- page? int - Set to 1 by default. The requested number of the page in paged response - Must be a number greater than 0.
- pageSize? int - Optional, it is set to 50 by default. The number of items to return per page in a paged response - Must be a number between 1 and 500.
- pageCount? int - Number of pages available
- itemCount? int - Number of items returned
xero.projects: Project
Fields
- projectId? string - Identifier of the project.
- contactId? string - Identifier of the contact this project was created for.
- name string - Name of the project.
- currencyCode? CurrencyCode - 3 letter alpha code for the ISO-4217 currency code, e.g. USD, AUD.
- minutesLogged? int - A total of minutes logged against all tasks on the Project.
- totalTaskAmount? Amount -
- totalExpenseAmount? Amount -
- estimateAmount? Amount -
- minutesToBeInvoiced? int - Minutes which have not been invoiced across all chargeable tasks in the project.
- taskAmountToBeInvoiced? Amount -
- taskAmountInvoiced? Amount -
- expenseAmountToBeInvoiced? Amount -
- expenseAmountInvoiced? Amount -
- projectAmountInvoiced? Amount -
- deposit? Amount -
- depositApplied? Amount -
- creditNoteAmount? Amount -
- deadlineUtc? string - Deadline for the project. UTC Date Time in ISO-8601 format.
- totalInvoiced? Amount -
- totalToBeInvoiced? Amount -
- estimate? Amount -
- status? ProjectStatus - Status for project
xero.projects: ProjectCreateOrUpdate
Fields
- contactId? string - Identifier of the contact this project was created for.
- name string - Name of the project.
- estimateAmount? decimal -
- deadlineUtc? string - Deadline for the project. UTC Date Time in ISO-8601 format.
xero.projects: ProjectPatch
Fields
- status ProjectStatus - Status for project
xero.projects: Projects
Fields
- pagination? Pagination -
- items? Project[] -
xero.projects: ProjectUser
Fields
- userId? string - Identifier of the user of the project.
- name? string - Full name of the user.
- email? string - Email address of the user.
xero.projects: ProjectUsers
Fields
- pagination? Pagination -
- items? ProjectUser[] -
xero.projects: ProxyConfig
Closed record
Proxy server configurations to be used with the HTTP client endpoint.
Fields
- host string(default "") - Host name of the proxy server
- port int(default 0) - Proxy server port
- userName string(default "") - Proxy server username
- password string(default "") - Proxy server password
xero.projects: Task
Fields
- taskId? string - Identifier of the task.
- name? string - Name of the task.
- rate? Amount -
- chargeType? ChargeType - Can be
TIME,FIXEDorNON_CHARGEABLE, defines how the task will be charged. UseTIMEwhen you want to charge per hour andFIXEDto charge as a fixed amount. If the task will not be charged useNON_CHARGEABLE.
- estimateMinutes? decimal - An estimated time to perform the task
- projectId? string - Identifier of the project task belongs to.
- totalMinutes? decimal - Total minutes which have been logged against the task. Logged by assigning a time entry to a task
- totalAmount? Amount -
- minutesInvoiced? decimal - Minutes on this task which have been invoiced.
- minutesToBeInvoiced? decimal - Minutes on this task which have not been invoiced.
- fixedMinutes? decimal - Minutes logged against this task if its charge type is
FIXED.
- nonChargeableMinutes? decimal - Minutes logged against this task if its charge type is
NON_CHARGEABLE.
- amountToBeInvoiced? Amount -
- amountInvoiced? Amount -
- status? string - Status of the task. When a task of ChargeType is
FIXEDand the rate amount is invoiced the status will be set toINVOICEDand can't be modified. A task with ChargeType ofTIMEorNON_CHARGEABLEcannot have a status ofINVOICED. ALOCKEDstate indicates that the task is currently changing state (for example being invoiced) and can't be modified.
xero.projects: TaskCreateOrUpdate
Fields
- name string - Name of the task. Max length 100 characters.
- rate Amount -
- chargeType ChargeType - Can be
TIME,FIXEDorNON_CHARGEABLE, defines how the task will be charged. UseTIMEwhen you want to charge per hour andFIXEDto charge as a fixed amount. If the task will not be charged useNON_CHARGEABLE.
- estimateMinutes? int - Estimated time to perform the task. EstimateMinutes has to be greater than 0 if provided.
xero.projects: Tasks
Fields
- pagination? Pagination -
- items? Task[] -
xero.projects: TimeEntries
Fields
- pagination? Pagination -
- items? TimeEntry[] -
xero.projects: TimeEntry
Fields
- timeEntryId? string - Identifier of the time entry.
- userId? string - The xero user identifier of the person who logged time.
- projectId? string - Identifier of the project, that the task (which the time entry is logged against) belongs to.
- taskId? string - Identifier of the task that time entry is logged against.
- dateUtc? string - The date time that time entry is logged on. UTC Date Time in ISO-8601 format.
- dateEnteredUtc? string - The date time that time entry is created. UTC Date Time in ISO-8601 format. By default it is set to server time.
- duration? int - The duration of logged minutes.
- description? string - A description of the time entry.
- status? string - Status of the time entry. By default a time entry is created with status of
ACTIVE. ALOCKEDstate indicates that the time entry is currently changing state (for example being invoiced). Updates are not allowed when in this state. It will have a status of INVOICED once it is invoiced.
xero.projects: TimeEntryCreateOrUpdate
Fields
- userId string - The xero user identifier of the person logging the time.
- taskId string - Identifier of the task that time entry is logged against.
- dateUtc string - Date time entry is logged on. UTC Date Time in ISO-8601 format.
- duration int - Number of minutes to be logged. Duration is between 1 and 59940 inclusively.
- description? string - An optional description of the time entry, will be set to null if not provided during update.
String types
xero.projects: CurrencyCode
CurrencyCode
3 letter alpha code for the ISO-4217 currency code, e.g. USD, AUD.
xero.projects: ProjectStatus
ProjectStatus
Status for project
xero.projects: ChargeType
ChargeType
Can be TIME, FIXED or NON_CHARGEABLE, defines how the task will be charged. Use TIME when you want to charge per hour and FIXED to charge as a fixed amount. If the task will not be charged use NON_CHARGEABLE.