Workity API

Deutsche Version dieser Seite: Programmierschnittstellen (API)

This page describes the application programming interface (API) for Simprove Workity. If you need additional support to develop Workity add-on applications (e.g. desktop or mobile clients, widgets, alternative Web front-ends, etc.), please use our contact form.

Only Premium members are able to develop Workity add-on applications using the application programming interface (API).

Only Premium members are able to use Workity add-on applications based on the application programming interface (API).

Table of Contents [Hide/Show]

Introduction
    Web service interface
    Ticket authentication
    Write-Write-Conflict
    Delete-Write-Conflict
Data types
    array
    boolean
    byte
    int
    long
    string
    dateTime
    Project
    ProjectInfo
    Person
    PersonInfo
    Keyword
    KeywordInfo
    Modification
    Upload
    TaskItem
    NoteItem
    FileItem
Functions
    AddKeywords
    AddPersons
    DeleteItems
    DownloadFile
    GetItems
    GetItemsByAdvancedSearch
    GetItemsByFullTextSearch
    GetItemsByNewsSearch
    GetKeywordID
    GetProjectKeywords
    GetProjectTeam
    GetUserInfo
    GetUserKeywords
    GetUserProjects
    GetUserTeam
    IsAuthenticated
    Login
    Logout
    NewFile
    NewNote
    NewTask
    RemoveKeywords
    RemovePersons
    ResetNews
    SaveFile
    SaveNote
    SaveTask
    UpdateTaskStatus
Examples
    HTML backup application

Edit

Introduction

Edit

Web service interface

The different functions of the Workity API are available as web service using the following URI:

https://www.workity.com/services/api.asmx

Opening this web service URI using a regular web browser shows all API functions and the associated WSDL service description. Selecting a specific function provides the SOAP 1.1 and SOAP 1.2 definition of a corresponding service request and response.

top

Edit

Ticket authentication

In order to avoid providing the user credentials (user email address and password) for each API function call, a so called ticket in the form of a GUID is used to authenticate a specific user. A successful call of the Login function providing valid credentials of a specific Workity user returns a new ticket for this user in the header of the associated SOAP response.

Example of a Login SOAP response including a GUID as ticket in the SOAP header:


<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <TicketHeader xmlns="http://www.workity.com/services/api">
      <Ticket>f30f74e1-05e0-43bc-8a93-1ac90106a986</Ticket>
    </TicketHeader>
  </soap:Header>
  <soap:Body>
    <LoginResponse xmlns="http://www.workity.com/services/api">
      <LoginResult>0</LoginResult>
    </LoginResponse>
  </soap:Body>
</soap:Envelope>

Each call of another API function must provide a valid ticket for the calling user in the header of the associated SOAP request to authenticate this user.

Example of a GetUserInfo SOAP request including a GUID as ticket in the SOAP header:


<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:xsd="http://www.w3.org/2001/XMLSchema" 
  xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <TicketHeader xmlns="http://www.workity.com/services/api">
      <Ticket>f30f74e1-05e0-43bc-8a93-1ac90106a986</Ticket>
    </TicketHeader>
  </soap:Header>
  <soap:Body>
    <GetUserInfo xmlns="http://www.workity.com/services/api" />
  </soap:Body>
</soap:Envelope>

A successful call of the Logout function disables the associated ticket. In doing so, this ticket cannot be used anymore to authenticate the calling user.

The IsAuthenticated function can be used to check, if the associated ticket is still valid.

A ticket automatically becomes invalid, when it hasn't been used for longer than 1 hour.

top

Edit

Write-Write-Conflict

A call of the functions SaveFile, SaveNote or SaveTask may produce a so called Write-Write-Conflict, when two or more members of the same project independently and quite simultaneously are editing the same revision x of a specific item (task, note or file) and save these changes with the same new revision x + 1 .

In case of a Write-Write-Conflict, the complete current content (except the assigned keywords and persons) of revision x + 1 of the affected item is copied to a new item before this content is overwritten with new content for revision x + 1. In addition, the affected item as well as its copy are both tagged with the !WRITE-WRITE-CONFLICT! keyword. This special keyword has the identification number 1, which is equal to the return value of the SaveFile, SaveNote or SaveTask function when a Write-Write-Conflict occurred.

When a file item is affected by a Write-Write-Conflict, a new note item with the file name as title and the file item details is created as copy. The binary content of the associated file is not copied and can only be downloaded using the original file item.

A Write-Write-Conflict can be solved by the involved persons using the GetItemsByAdvancedSearch function to search for all items tagged with the keyword with identification number 1. Afterwards, the content of the resulting items can be merged into one single item and the obsolete copies can be deleted using the DeleteItems function. Furthermore, the !WRITE-WRITE-CONFLICT! keyword can be removed from the resulting item using the RemoveKeywords function.

Example: Lenny and Carl create together a note item as guest list for their collective birthday party. This note item has currently the revision number 10 and is independently and simultaneously edited by Lenny and Carl. First, Lenny adds Homer to the guest list and saves the item with the new revision 11. Right afterwards, Carl also saves this note item with revision 11, because he added Ned to the guest list. In doing so, a Write-Write-Conflict occurred and is indicated to Carl by receiving 1 as return value of his SaveNote function call. Now, Carl calls the GetItemsByAdvancedSearch to search for the two note items tagged with the keyword with identification number 1. Comparing the details of these items, Carl recognizes that Lenny added Homer to the guest list. So Carl also adds Homer to the latest list already including Ned. Then he deletes the obsolete copy by calling the DeleteItems function. Furthermore, he also removes the !WRITE-WRITE-CONFLICT! keyword from the original note item by calling the RemoveKeywords function.

see also: Delete-Write-Conflict, SaveFile, SaveNote, SaveTask

top

Edit

Delete-Write-Conflict

A call of the functions SaveFile, SaveNote or SaveTask may produce a so called Delete-Write-Conflict, when independently a project member deletes a specific item (task, note or file) and right afterwards another project member attempts to save this item.

In case of a Delete-Write-Conflict, the new content of the recently deleted item is saved into a new item of the associated project. In addition, this new item is tagged with the !DELETE-WRITE-CONFLICT! keyword. This special keyword has the identification number 2, which is equal to the return value of the SaveFile, SaveNote or SaveTask function when a Delete-Write-Conflict occurred.

When a file item is affected by a Delete-Write-Conflict, only the new details of this file item are saved into a new note item with title ???. The binary content of the affected file is irrevocable deleted.

A Delete-Write-Conflict can be solved by the involved persons using the GetItemsByAdvancedSearch function to search for the item tagged with the keyword with identification number 2. Depending on the relevance of its content, this item can be either deleted again using the DeleteItems function or it can be re-assigned with related persons and keywords using the AddPersons and AddKeywords functions. Furthermore, the RemoveKeywords function can be used to remove the !DELETE-WRITE-CONFLICT! keyword from this item.

Example: Lenny and Carl organized a collective birthday party. After the party, Lenny wants to add some new contact information to the note item containing the guest list, because he wants to use this list again the next year. While Lenny is editing the list, Carl independently deletes this note item. When Lenny attempts to save his changes by calling the SaveNote function, a return value of 2 indicates him that a Delete-Write-Conflict occurred. Now, Lenny calls the GetItemsByAdvancedSearch function to search for the item tagged with the keyword with the identification number 2. Since Lenny still wants to keep the guest list, he calls the AddPersons function to re-assign himself to the resulting note item. Furthermore, he removes the !DELETE-WRITE-CONFLICT! keyword from this item using the RemoveKeywords function.

see also: Write-Write-Conflict, SaveFile, SaveNote, SaveTask

top

Edit

Data types

Edit

array

Within this documentation an array of a specific data type is described using the notation type-array. For instance, the notation long-array represents an array of long values.

top

Edit

boolean

Represents a true/false value.

top

Edit

byte

Represents an 8-bit unsigned integer value in the range 0 to 255.

top

Edit

int

Represents a 32-bit signed integer value in the range -2,147,483,648 to 2,147,483,647.

top

Edit

long

Represents a 64-bit signed integer value in the range –9,223,372,036,854,775,808 to 9,223,372,036,854,775,807.

top

Edit

string

Represents a string value in Unicode format.

top

Edit

dateTime

Represents a specific date and time using the ISO 8601 Standard format:

YYYY-MM-DDThh:mmTZD (e.g. 1989-11-09T22:30 represents November 9, 1989 at 10:30 pm)

YYYY = 4-digit year (e.g. 1989)
MM = 2-digit month (01 = January, 02 = February, etc.)
DD = 2-digit day of month (01 through 31)
hh = 2-digit hour (00 through 23, am/pm NOT allowed)
mm = 2-digit minute (00 through 59)
TZD = optional time zone designator (Z or +hh:mm or -hh:mm)

A valid dateTime value may also include 2 digits of second, but this part will be ignored. In doing so, the dateTime values 1989-11-09T22:30:01 and 1989-11-09T22:30:59 are interpreted to be equal.

A valid dateTime value must be in the range 1900-01-01T00:00 to 2079-06-06T23:59.

top

Edit

Project

Data structure representing a short project description with the following elements:

Data type	Name	Description
long	ProjectID	project identification number
string	Name	name of the project

top

Edit

ProjectInfo

Data structure representing a detailed project description with the following elements:

Data type	Name	Description
long	ProjectID	project identification number
string	Name	name of the project

Currently, this definition is equal to the Project data structure but may be extended by additional elements.

top

Edit

Person

Data structure representing a short person description with the following elements:

Data type	Name	Description
long	PersonID	person identification number
string	Name	name of the person

top

Edit

PersonInfo

Data structure representing a detailed person description with the following elements:

Data type	Name	Description
long	PersonID	person identification number
string	Name	name of the person
string	PictureURL	URL pointing to the profile picture of the person.

top

Edit

Keyword

Data structure representing a short keyword description with the following elements:

Data type	Name	Description
long	KeywordID	keyword identification number
string	Name	keyword label

top

Edit

KeywordInfo

Data structure representing a detailed keyword description with the following elements:

Data type	Name	Description
long	KeywordID	keyword identification number
string	Name	keyword label
int	UsageCount	Count how often this keyword is currently used.

The UsageCount value can be used to display a specific set of keywords like a so called tag cloud.

top

Edit

Modification

Data structure representing the person and the date in connection with the last modification of an item (task, note or file):

Data type	Name	Description
Person	Person	Person who lastly modified the item.
dateTime	Date	Date when the item has been lastly modified.

top

Edit

Upload

Data structure representing the person and the date in connection with an uploaded file:

Data type	Name	Description
Person	Person	Person who uploaded the file.
dateTime	Date	Date when the file has been uploaded.

top

Edit

TaskItem

Data structure representing a task item with the following elements:

Data type	Name	Description
long	TaskID	task identification number
Project	Project	identification number of the associated project
string	Title	title of the task item
string	Details	details of the task item
boolean	IsFinished	status of the task
dateTime	DueDate	due date of the task
Modification	Modification	details about the last modification of the task item
Person-array	Persons	Persons assigned to the task item.
Keyword-array	Keywords	Keywords assigned to the task item.
int	Revision	Count how often the task item has been modified.

top

Edit

NoteItem

Data structure representing a note item with the following elements:

Data type	Name	Description
long	NoteID	note identification number
Project	Project	identification number of the associated project
string	Title	title of the note item
string	Details	details of the note item
Modification	Modification	details about the last modification of the note item
Person-array	Persons	Persons assigned to the note item.
Keyword-array	Keywords	Keywords assigned to the note item.
int	Revision	Count how often the note item has been modified.

top

Edit

FileItem

Data structure representing a file item with the following elements:

Data type	Name	Description
long	FileID	file identification number
Project	Project	identification number of the associated project
string	Name	file name
string	ContentType	content type of the file, e.g. text/plain, image/jpeg, application/pdf, etc.
long	Size	file size in bytes
string	Details	details of the file item
Upload	Upload	details about the file upload
Modification	Modification	details about the last modification of the file item
Person-array	Persons	Persons assigned to the file item.
Keyword-array	Keywords	Keywords assigned to the file item.
int	Revision	Count how often the file item has been modified.

top

Edit

Functions

Edit

AddKeywords

Assigns a set of keywords to a set of items (tasks, notes, files).

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long-array	TaskIDs	Identification numbers of task items which should be tagged with the given keywords.
long-array	NoteIDs	Identification numbers of note items which should be tagged with the given keywords.
long-array	FileIDs	Identification numbers of file items which should be tagged with the given keywords.
long-array	KeywordIDs	Identification numbers of keywords which should be assigned to the given items.
dateTime	ModificationDate	Local date of the calling user when the given items will be modified.

Invalid identification numbers of items or keywords will be ignored.

Return value: This function has no return value.

see also: RemoveKeywords

top

Edit

AddPersons

Assigns a set of persons to a set of items (tasks, notes, files).

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long-array	TaskIDs	Identification numbers of task items which should be tagged with the given persons.
long-array	NoteIDs	Identification numbers of note items which should be tagged with the given persons.
long-array	FileIDs	Identification numbers of file items which should be tagged with the given persons.
long-array	PersonIDs	Identification numbers of persons who should be assigned to the given items.
dateTime	ModificationDate	Local date of the calling user when the given items will be modified.

Invalid identification numbers of items or persons will be ignored.

Return value: This function has no return value.

see also: RemovePersons

top

Edit

DeleteItems

Deletes a set of items (tasks, notes, files).

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long-array	TaskIDs	Identification numbers of task items which should be deleted.
long-array	NoteIDs	Identification numbers of note items which should be deleted.
long-array	FileIDs	Identification numbers of file items which should be deleted.

Invalid identification numbers of items will be ignored.

Return value: This function has no return value.

top

Edit

DownloadFile

Downloads a specific file.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long	FileID	Identification number of the file which should be downloaded.

Return value:

Data type	Name	Description
string	Name	name of the downloaded file
string	ContentType	content type of the downloaded file, e.g. text/plain, image/jpeg, application/pdf, etc.
byte-array	Bytes	binary content of the downloaded file

GetItems

Returns a set of specific items (tasks, notes, files).

SOAP 1.1 and SOAP 1.2 description of this function

Parameter:

Data type	Name	Description
long-array	TaskIDs	Identification numbers of task items which should be returned.
long-array	NoteIDs	Identification numbers of note items which should be returned.
long-array	FileIDs	Identification numbers of file items which should be returned.
boolean	IsDetails	Flag specifying whether the content of the Details property of the requested items should be returned or not.

Invalid identification numbers of items will be ignored.

Return value:

Data type	Name	Description
TaskItem-array	TaskItems	Task items which have been requested by the TaskIDs argument.
NoteItem-array	NoteItems	Note items which have been requested by the NoteIDs argument.
FileItem-array	FileItems	File items which have been requested by the FileIDs argument.

GetItemsByAdvancedSearch

Returns a set of items (tasks, notes, files) matching specific search parameters.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
string	SearchString	Search string used to find specific items. This value can be defined like usual search strings in connection with Web search engines (e.g. Google). An empty search string will be ignored as search option for specific items. A value with more than 50 characters throws an exception.
long-array	ProjectIDs	Identification numbers of active projects of the calling user to be searched for specific items. If no project identification numbers are specified by this argument (empty array), all active projects of the calling user will be searched for specific items.
long-array	PersonIDs	Identification numbers of persons who must be assigned to the returning items.
long-array	KeywordIDs	Identification numbers of keywords which must be assigned to the returning items.
boolean	IsUnfinishedTasks	Flag specifying whether to search for unfinished task items or not.
boolean	IsFinishedTasks	Flag specifying whether to search for finished task items or not.
boolean	IsMinDueDate	Flag specifying whether to search for task items whose due date is greater or equal to the value of the MinDueDate argument or not.
dateTime	MinDueDate	minimum task due date This value will be ignored in case the IsMinDueDate argument is false.
boolean	IsMaxDueDate	Flag specifying whether to search for task items whose due date is less or equal to the value of the MaxDueDate argument or not.
dateTime	MaxDueDate	maximum task due date This value will be ignored in case the IsMaxDueDate argument is false.
boolean	IsNotes	Flag specifying whether to search for note items or not.
boolean	IsFiles	Flag specifying whether to search for file items or not.
boolean	IsModificationDate	Flag specifying whether to search for items whose last modification date is greater or equal to the value of the ModificationDate argument or not.
dateTime	ModificationDate	minimum modification date This value will be ignored in case the IsModificationDate argument is false.
boolean	IsModificationPerson	Flag specifying whether to search for items which have been lastly modified by a specific person or not.
long	ModificationPersonID	Identification number of the person who has lastly modified the returning items. This value will be ignored in case the IsModificationPerson argument is false.
boolean	IsDetails	Flag specifying whether the content of the Details property of the found items should be returned or not.

Invalid identification numbers of projects, persons or keywords return no items.

Return value:

Data type	Name	Description
TaskItem-array	TaskItems	Task items which are matching the search parameters.
NoteItem-array	NoteItems	Note items which are matching the search parameters.
FileItem-array	FileItems	File items which are matching the search parameters.

see also: GetItems, GetItemsByNewsSearch

top

Edit

GetItemsByFullTextSearch

Returns a set of items (taks, notes, files) matching a specific search string.

This function is obsolete and should not be used anymore. Please use the GetItemsByAdvancedSearch function instead to search for items (taks, notes, files) matching a specific search string.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
string	SearchString	Search string used to find specific items. This value can be defined like usual search strings in connection with Web search engines (e.g. Google). A value with more than 50 characters throws an exception.
long-array	ProjectIDs	Identification numbers of active projects of the calling user to be searched for specific items. If no project identification numbers are specified by this argument (empty array), all active projects of the calling user will be searched for specific items.
boolean	IsUnfinishedTasks	Flag specifying whether to search for unfinished task items or not.
boolean	IsFinishedTasks	Flag specifying whether to search for finished task items or not.
boolean	IsNotes	Flag specifying whether to search for note items or not.
boolean	IsFiles	Flag specifying whether to search for file items or not.
boolean	IsDetails	Flag specifying whether the content of the Details property of the found items should be returned or not.

Return value:

Data type	Name	Description
TaskItem-array	TaskItems	Task items whose Title or Details property are matching the search string.
NoteItem-array	NoteItems	Note items whose Title or Details property are matching the search string.
FileItem-array	FileItems	File items whose Name or Details property are matching the search string.

GetItemsByNewsSearch

Returns a set of items (tasks, notes, files) matching specific search parameters and which have been modified since the last call of the ResetNews function by another person than the calling user.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long-array	ProjectIDs	Identification numbers of active projects of the calling user to be searched for specific items. If no project identification numbers are specified by this argument (empty array), all active projects of the calling user will be searched for specific items.
long-array	PersonIDs	Identification numbers of persons who must be assigned to the returning items.
long-array	KeywordIDs	Identification numbers of keywords which must be assigned to the returning items.
boolean	IsUnfinishedTasks	Flag specifying whether to search for unfinished task items or not.
boolean	IsFinishedTasks	Flag specifying whether to search for finished task items or not.
boolean	IsNotes	Flag specifying whether to search for note items or not.
boolean	IsFiles	Flag specifying whether to search for file items or not.
boolean	IsDetails	Flag specifying whether the content of the Details property of the found items should be returned or not.

Invalid identification numbers of projects, persons or keywords return no items.

Return value:

Data type	Name	Description
TaskItem-array	TaskItems	Task items which are matching the search parameters and which have been modified since the last call of the ResetNews function by another person than the calling user.
NoteItem-array	NoteItems	Note items which are matching the search parameters and which have been modified since the last call of the ResetNews function by another person than the calling user.
FileItem-array	FileItems	File items which are matching the search parameters and which have been modified since the last call of the ResetNews function by another person than the calling user.

see also: ResetNews, GetItems, GetItemsByAdvancedSearch

top

Edit

GetKeywordID

Returns the identification number of a new or existing keyword.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
string	Keyword	Keyword whose identification number will be returned. The value of this argument must match the following regular expression: ^\S{1,20}$

Return value:

Data type	Description
long	identification number of the given keyword

top

Edit

GetProjectKeywords

Returns all keywords assigned to items (tasks, notes, files) of a specific active project of the calling user.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long	ProjectID	Identification number of the project whose keywords will be returned. An invalid project identification number throws an exception.

Return value:

Data type	Description
KeywordInfo-array	Alphabetical ordered list of all keywords assigned to items of the given project.

GetProjectTeam

Returns all team members of a specific active project of the calling user.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long	ProjectID	Identification number of the project whose team members will be returned. An invalid project identification number throws an exception.

Return value:

Data type	Description
PersonInfo-array	alphabetical ordered list of all team members of the given project

GetUserInfo

Returns information about the calling user.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments: This function has no arguments.

Return value:

Data type	Name	Description
long	UserID	identification number of the calling user
string	Name	Name of the calling user
string	PictureURL	URL pointing to the profile picture of the calling user
long	FreeFileStorage	Free file storage in bytes still available for the calling user to upload files.

see also: GetUserKeywords, GetUserProjects, GetUserTeam

top

Edit

GetUserKeywords

Returns all keywords assigned to items (tasks, notes, files) of any active project of the calling user. In doing so, the result equates to the list of keywords displayed on the classic Workity dashboard.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments: This function has no arguments.

Return value:

Data type	Description
KeywordInfo-array	Alphabetical ordered list of all keywords assigned to items of any active project of the calling user.

GetUserProjects

Returns all active projects of the calling user.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments: This function has no arguments.

Return value:

Data type	Description
ProjectInfo-array	alphabetical ordered list of all active projects of the calling user

see also: GetUserInfo, GetUserKeywords, GetUserTeam

top

Edit

GetUserTeam

Returns all team members of all active projects of the calling user. In doing so, the result equates to the list of persons (including the calling user) displayed on the classic Workity dashboard.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments: This function has no arguments.

Return value:

Data type	Description
PersonInfo-array	alphabetical ordered list of all team members of all active projects of the calling user

IsAuthenticated

Checks, if the authentication of the calling user is valid.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments: This function has no arguments.

Return value:

Data type	Description
boolean	true: The authentication of the calling user is (still) valid. false: The authentication of the calling user is not valid (anymore).

see also: Ticket authentication, Login, Logout

top

Edit

Login

Authenticates a specific Workity user based on the associated user credentials.

Without a valid user authentication no other function of the Workity API can be successfully called.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
string	Email	User email address of the Workity user who wants to be authenticated.
string	Password	Password of the Workity user who wants to be authenticated.

Return value:

Data type

Description

int

0: User authentication has been successful.
-1: User authentication failed, because an invalid user email address and/or an invalid user password has been provided.
-2: User authentication failed, because the user with the given user email address is currently locked due to more than 5 invalid authentication attempts.
-3: User authentication failed, because the user with the given user email address has not yet accepted the Workity Terms of Service/Privacy Policy.
-4: User authentication failed, because the user with the given user email address is currently not a Workity Premium member.

Logout

Disables the authentication of the calling user.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments: This function has no arguments.

Return value:

Data type	Description
boolean	true: The authentication of the calling user was still valid at the calling time. false: The authentication of the calling user was already invalid at the calling time.

see also: Ticket authentication, Login, IsAuthenticated

top

Edit

NewFile

Creates a new file item.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long	ProjectID	Identification number of the project to which the new file item belongs. An invalid project identification number throws an exception.
long-array	PersonIDs	Identification numbers of persons who will be assigned to the new file item. Invalid identification numbers of persons who are not members of the project given by the ProjectID argument will be ignored. If no valid identification numbers of persons are given by this argument, the new file item will be automatically assigned to the calling user.
long-array	KeywordIDs	Identification numbers of keywords which will be assigned to the new file item. Invalid identification numbers of keywords will be ignored.
string	Name	file name An empty string or a value with more than 100 characters throws an exception.
string	ContentType	content type of the file, e.g. text/plain, image/jpeg, application/pdf, etc. An empty string or a value with more than 100 characters throws an exception.
string	Details	details of the new file item
byte-array	Bytes	binary content of the file An empty array throws an exception.
dateTime	ModificationDate	Local date of the calling user when the new file item will be created.

Return value:

Data type	Description
long	Identification number of the new file item If not enough free file storage space is available for the calling user to upload the new file, the function returns -1.

NewNote

Creates a new note item.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long	ProjectID	Identification number of the project to which the new note item belongs. An invalid project identification number throws an exception.
long-array	PersonIDs	Identification numbers of persons who will be assigned to the new note item. Invalid identification numbers of persons who are not members of the project given by the ProjectID argument will be ignored. If no valid identification numbers of persons are given by this argument, the new note item will be automatically assigned to the calling user.
long-array	KeywordIDs	Identification numbers of keywords which will be assigned to the new note item. Invalid identification numbers of keywords will be ignored.
string	Title	title of the new note item An empty string or a value with more than 100 characters throws an exception.
string	Details	details of the new note item
dateTime	ModificationDate	Local date of the calling user when the new note item will be created.

Return value:

Data type	Description
long	Identification number of the new note item

NewTask

Creates a new task item.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long	ProjectID	Identification number of the project to which the new task item belongs. An invalid project identification number throws an exception.
long-array	PersonIDs	Identification numbers of persons who will be assigned to the new task item. Invalid identification numbers of persons who are not members of the project given by the ProjectID argument will be ignored. If no valid identification numbers of persons are given by this argument, the new task item will be automatically assigned to the calling user.
long-array	KeywordIDs	Identification numbers of keywords which will be assigned to the new task item. Invalid identification numbers of keywords will be ignored.
string	Title	title of the new task item An empty string or a value with more than 100 characters throws an exception.
string	Details	details of the new task item
dateTime	DueDate	due date of the task
dateTime	ModificationDate	Local date of the calling user when the new task item will be created.

Return value:

Data type	Description
long	Identification number of the new task item

RemoveKeywords

Removes a set of keywords from a set of items (tasks, notes, files).

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long-array	TaskIDs	Identification numbers of task items which should not be tagged with the given keywords anymore.
long-array	NoteIDs	Identification numbers of note items which should not be tagged with the given keywords anymore.
long-array	FileIDs	Identification numbers of file items which should not be tagged with the given keywords anymore.
long-array	KeywordIDs	Identification numbers of keywords which should be removed from the given items.
dateTime	ModificationDate	Local date of the calling user when the given items will be modified.

Invalid identification numbers of items or keywords will be ignored.

Return value: This function has no return value.

see also: AddKeywords

top

Edit

RemovePersons

Removes a set of persons from a set of items (tasks, notes, files).

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long-array	TaskIDs	Identification numbers of task items which should not be tagged with the given persons anymore.
long-array	NoteIDs	Identification numbers of note items which should not be tagged with the given persons anymore.
long-array	FileIDs	Identification numbers of file items which should not be tagged with the given persons anymore.
long-array	PersonIDs	Identification numbers of persons who should be removed from the given items.
dateTime	ModificationDate	Local date of the calling user when the given items will be modified.

Invalid identification numbers of items or persons will be ignored.

Return value: This function has no return value.

see also: AddPersons

top

Edit

ResetNews

When this function has been called, the GetItemsByNewsSearch function returns only items (tasks, notes, files) which have been modified afterwards by another person than the calling user. In other words, calling this function resets the set of items which have been returned by the GetItemsByNewsSearch function before.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments: This function has no arguments.

Return value: This function has no return value.

see also: GetItemsByNewsSearch

top

Edit

SaveFile

Saves an existing file item.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long	ProjectID	identification number of the associated project An invalid project identification number throws an exception.
long	FileID	identification number of the file item
string	Details	details of the file item
int	NewRevision	new revision of the file item The new revision should always be the current revision + 1. A new revision less than 1 or greater than the current revision + 1 throws an exception.
dateTime	ModificationDate	Local date of the calling user when the file item will be saved.

Return value:

Data type	Description
long	0: The file item has been saved successfully. 1: Saving the file item caused a Write-Write-Conflict. 2: Saving the file item caused a Delete-Write-Conflict.

SaveNote

Saves an existing note item.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long	ProjectID	identification number of the associated project An invalid project identification number throws an exception.
long	NoteID	identification number of the note item
string	Title	title of the note item An empty string or a value with more than 100 characters throws an exception.
string	Details	details of the note item
int	NewRevision	new revision of the note item The new revision should always be the current revision + 1. A new revision less than 1 or greater than the current revision + 1 throws an exception.
dateTime	ModificationDate	Local date of the calling user when the note item will be saved.

Return value:

Data type	Description
long	0: The note item has been saved successfully. 1: Saving the note item caused a Write-Write-Conflict. 2: Saving the note item caused a Delete-Write-Conflict.

SaveTask

Saves an existing task item.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long	ProjectID	identification number of the associated project An invalid project identification number throws an exception.
long	TaskID	identification number of the task item
string	Title	title of the task item An empty string or a value with more than 100 characters throws an exception.
string	Details	details of the task item
dateTime	DueDate	due date of the task
int	NewRevision	new revision of the task item The new revision should always be the current revision + 1. A new revision less than 1 or greater than the current revision + 1 throws an exception.
dateTime	ModificationDate	Local date of the calling user when the task item will be saved.

Return value:

Data type	Description
long	0: The task item has been saved successfully. 1: Saving the task item caused a Write-Write-Conflict. 2: Saving the task item caused a Delete-Write-Conflict.

UpdateTaskStatus

Updates the status of a task.

SOAP 1.1 and SOAP 1.2 description of this function

Arguments:

Data type	Name	Description
long	TaskID	identification number of the associated task item An invalid identification number throws an exception.
boolean	IsFinished	new status of the task true: The task is now finished. false: The task is not finished yet.
dateTime	ModificationDate	Local date of the calling user when the given task item will be modified.

Return value: This function has no return value.

top

Edit

Examples

Edit

HTML backup application

The HTML backup application is a simple Windows console application to automatically create regular backups of the complete content of all projects in HTML format.

After the application has been started, the user email address and password of a Workity Premium user is requested. If the user authentication has been successful, an HTML file with the complete content (tasks, notes, files) of all active projects of the given user is created in the application directory.

In doing so, the console application combines the following actions of the Workity web-application:

selection of all active projects on the dashboard
execution of the "Show items" action
selection of all items on the dashboard
execution of the "Export selected items as HTML file" action

Download application: WorkityBackup.zip (20 KB)

Download C# source code of the application as Microsoft Visual Studio project: WorkityBackupSource.zip (151 KB)

see also: How can I export content of my projects?

top

Deutsche Version dieser Seite: Programmierschnittstellen (API)