Contact

Requires Pro Edition and CRM plugin >= 3.3.0.

Manager

All operations on the Contact resource are provided by its manager. To get access to it you have to call redmine.contact where redmine is a configured redmine object. See the Configuration about how to configure redmine object.

Create methods

create

redminelib.managers.ResourceManager.create(**fields)

Creates new Contact resource with given fields and saves it to the CRM plugin.

Parameters:

• project_id (int or string) – (required). Id or identifier of contact’s project.

• first_name (string) – (required). Contact first name.

• last_name (string) – (optional). Contact last name.

• middle_name (string) – (optional). Contact middle name.

• company (string) – (optional). Contact company name.

• phones (list) – (optional). List of phone numbers.

• emails (list) – (optional). List of emails.

• website (string) – (optional). Contact website.

• skype_name (string) – (optional). Contact skype.

• birthday (string or date object) – (optional). Contact birthday.

• background (string) – (optional). Contact background.

• job_title (string) – (optional). Contact job title.

• tag_list (list) – (optional). List of tags.

• is_company (bool) – (optional). Whether contact is a company.

• assigned_to_id (int) – (optional). Contact will be assigned to this user id.

• custom_fields (list) – (optional). Custom fields as [{‘id’: 1, ‘value’: ‘foo’}].

• address_attributes (dict) – (optional). Address attributes as dict, available keys are:

  • street1 - first line for the street details

  • street2 - second line for the street details

  • city - city

  • region - region (state)

  • postcode - ZIP code

  • country_code - country code as two-symbol abbreviation (e.g. US)

• visibility (int) – (optional). Contact visibility:

  • 0 - project

  • 1 - public

  • 2 - private

• avatar (dict) – (optional). Avatar to be used for the contact as dict, accepted keys are:

  • path (required). Absolute file path or file-like object that should be uploaded.

  • filename (optional). Required if a file-like object is provided.

Returns:

Resource object

>>> contact = redmine.contact.create(
...     project_id='vacation',
...     first_name='Ivan',
...     last_name='Ivanov',
...     middle_name='Ivanovich',
...     company='Ivan Gmbh',
...     phones=['1234567'],
...     emails=['ivan@ivanov.com'],
...     website='ivanov.com',
...     skype_name='ivan.ivanov',
...     birthday=datetime.date(1980, 10, 21),
...     background='some background here',
...     job_title='CEO',
...     tag_list=['vip', 'online'],
...     is_company=False,
...     address_attributes={'street1': 'foo', 'street2': 'bar', 'city': 'Moscow', 'postcode': '111111', 'country_code': 'RU'},
...     custom_fields=[{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}],
...     visibility=0,
...     avatar={'path': '/absolute/path/to/file.jpg'}
... )
>>> contact
<redminelib.resources.Contact #1 "Ivan Ivanov">

new

redminelib.managers.ResourceManager.new()

Creates new empty Contact resource but saves it to the the CRM plugin only when save() is called, also calls pre_create() and post_create() methods of the Resource object. Valid attributes are the same as for create() method above.

Returns:

Resource object

>>> contact = redmine.contact.new()
>>> contact.project_id = 'vacation'
>>> contact.first_name = 'Ivan'
>>> contact.last_name = 'Ivanov'
>>> contact.middle_name = 'Ivanovich'
>>> contact.company = 'Ivan Gmbh'
>>> contact.phones = ['1234567']
>>> contact.emails = ['ivan@ivanov.com']
>>> contact.website = 'ivanov.com'
>>> contact.skype_name = 'ivan.ivanov'
>>> contact.birthday = datetime.date(1980, 10, 21)
>>> contact.background = 'some background here'
>>> contact.job_title = 'CEO'
>>> contact.tag_list = ['vip', 'online']
>>> contact.is_company = False
>>> contact.address_attributes = {'street1': 'foo', 'street2': 'bar', 'city': 'Moscow', 'postcode': '111111', 'country_code': 'RU'}
>>> contact.custom_fields = [{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}]
>>> contact.visibility = 0
>>> contact.avatar = {'path': '/absolute/path/to/file.jpg'}
>>> contact.save()
<redminelib.resources.Contact #1 "Ivan Ivanov">

Read methods

get

redminelib.managers.ResourceManager.get(resource_id, **params)

Returns single Contact resource from the CRM plugin by its id.

Parameters:

• resource_id (int) – (required). Id of the contact.

• include (list) – (optional). Fetches associated data in one call. Accepted values:

  • notes

  • contacts

  • deals

  • issues

  • projects

  • tickets (requires Pro Edition and Helpdesk plugin >= 4.1.12)

Returns:

Resource object

>>> contact = redmine.contact.get(12345, include=['notes', 'contacts', 'deals', 'issues', 'projects'])
>>> contact
<redminelib.resources.Contact #12345 "Ivan Ivanov">

Hint

Contact resource object provides you with on demand includes. On demand includes are the other resource objects wrapped in a ResourceSet which are associated with a Contact resource object. Keep in mind that on demand includes are retrieved in a separate request, that means that if the speed is important it is recommended to use get() method with include keyword argument. On demand includes provided by the Contact resource object are the same as in the get() method above:

>>> contact = redmine.contact.get(12345)
>>> contact.issues
<redminelib.resultsets.ResourceSet object with Issue resources>

Hint

Contact resource object provides you with some relations. Relations are the other resource objects wrapped in a ResourceSet which are somehow related to a Contact resource object. The relations provided by the Contact resource object are:

• invoices (requires Pro Edition and Invoices plugin >= 4.1.3)

• payments (requires Pro Edition and Invoices plugin >= 4.1.3)

• expenses (requires Pro Edition and Invoices plugin >= 4.1.3)

• orders (requires Pro Edition and Products plugin >= 2.1.5)

>>> contact = redmine.contact.get(12345)
>>> contact.invoices
<redminelib.resultsets.ResourceSet object with Invoice resources>

all

redminelib.managers.ResourceManager.all(**params)

Returns all Contact resources from the CRM plugin.

Parameters:

• limit (int) – (optional). How much resources to return.

• offset (int) – (optional). Starting from what resource to return the other resources.

• include (list) – (optional). Fetches associated data in one call. Accepted values:

  • projects

Returns:

ResourceSet object

>>> contacts = redmine.contact.all(offset=10, limit=100, include=['projects'])
>>> contacts
<redminelib.resultsets.ResourceSet object with Contact resources>

filter

redminelib.managers.ResourceManager.filter(**filters)

Returns Contact resources that match the given lookup parameters.

Parameters:

• project_id (int or string) – (optional). Id or identifier of contact’s project.

• assigned_to_id (int) – (optional). Get contacts assigned to this user id.

• query_id (int) – (optional). Get contacts for the given query id.

• search (string) – (optional). Get contacts with given search string.

• tags (string) – (optional). Get contacts with given tags (separated by ,).

• limit (int) – (optional). How much resources to return.

• offset (int) – (optional). Starting from what resource to return the other resources.

• include (list) – (optional). Fetches associated data in one call. Accepted values:

  • projects

Returns:

ResourceSet object

>>> contacts = redmine.contact.filter(project_id='vacation', assigned_to_id=123, search='Smith', tags='one,two', include=['projects'])
>>> contacts
<redminelib.resultsets.ResourceSet object with Contact resources>

Hint

You can also get contacts from a Project and User resource objects directly using contacts relation:

>>> project = redmine.project.get('vacation')
>>> project.contacts
<redminelib.resultsets.ResourceSet object with Contact resources>

Update methods

update

redminelib.managers.ResourceManager.update(resource_id, **fields)

Updates values of given fields of a Contact resource and saves them to the CRM plugin.

Parameters:

• resource_id (int) – (required). Contact id.

• first_name (string) – (optional). Contact first name.

• last_name (string) – (optional). Contact last name.

• middle_name (string) – (optional). Contact middle name.

• company (string) – (optional). Contact company name.

• phones (list) – (optional). List of phone numbers.

• emails (list) – (optional). List of emails.

• website (string) – (optional). Contact website.

• skype_name (string) – (optional). Contact skype.

• birthday (string or date object) – (optional). Contact birthday.

• background (string) – (optional). Contact background.

• job_title (string) – (optional). Contact job title.

• tag_list (list) – (optional). List of tags.

• is_company (bool) – (optional). Whether contact is a company.

• assigned_to_id (int) – (optional). Contact will be assigned to this user id.

• custom_fields (list) – (optional). Custom fields as [{‘id’: 1, ‘value’: ‘foo’}].

• address_attributes (dict) – (optional). Address attributes as dict, available keys are:

  • street1 - first line for the street details

  • street2 - second line for the street details

  • city - city

  • region - region (state)

  • postcode - ZIP code

  • country_code - country code as two-symbol abbreviation (e.g. US)

• visibility (int) – (optional). Contact visibility:

  • 0 - project

  • 1 - public

  • 2 - private

• avatar (dict) – (optional). Avatar to be used for the contact as dict, accepted keys are:

  • path (required). Absolute file path or file-like object that should be uploaded.

  • filename (optional). Required if a file-like object is provided.

Returns:

True

>>> redmine.contact.update(
...     12345,
...     first_name='Ivan',
...     last_name='Ivanov',
...     middle_name='Ivanovich',
...     company='Ivan Gmbh',
...     phones=['1234567'],
...     emails=['ivan@ivanov.com'],
...     website='ivanov.com',
...     skype_name='ivan.ivanov',
...     birthday=datetime.date(1980, 10, 21),
...     background='some background here',
...     job_title='CEO',
...     tag_list=['vip', 'online'],
...     is_company=False,
...     address_attributes={'street1': 'foo', 'street2': 'bar', 'city': 'Moscow', 'postcode': '111111', 'country_code': 'RU'},
...     custom_fields=[{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}],
...     visibility=0,
...     avatar={'path': '/absolute/path/to/file.jpg'}
... )
True

save

redminelib.resources.Contact.save(**attrs)

Saves the current state of a Contact resource to the CRM plugin. Attrs that can be changed are the same as for update() method above.

Returns:

Resource object

>>> contact = redmine.contact.get(12345)
>>> contact.first_name = 'Ivan'
>>> contact.last_name = 'Ivanov'
>>> contact.middle_name = 'Ivanovich'
>>> contact.company = 'Ivan Gmbh'
>>> contact.phones = ['1234567']
>>> contact.emails = ['ivan@ivanov.com']
>>> contact.website = 'ivanov.com'
>>> contact.skype_name = 'ivan.ivanov'
>>> contact.birthday = datetime.date(1980, 10, 21)
>>> contact.background = 'some background here'
>>> contact.job_title = 'CEO'
>>> contact.tag_list = ['vip', 'online']
>>> contact.is_company = False
>>> contact.address_attributes = {'street1': 'foo', 'street2': 'bar', 'city': 'Moscow', 'postcode': '111111', 'country_code': 'RU'}
>>> contact.custom_fields = [{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}]
>>> contact.visibility = 0
>>> contact.avatar = {'path': '/absolute/path/to/file.jpg'}
>>> contact.save()
<redminelib.resources.Contact #12345 "Ivan Ivanov">

Added in version 2.1.0: Alternative syntax was introduced.

>>> contact = redmine.contact.get(12345).save(
...     first_name='Ivan',
...     last_name='Ivanov',
...     middle_name='Ivanovich',
...     company='Ivan Gmbh',
...     phones=['1234567'],
...     emails=['ivan@ivanov.com'],
...     website='ivanov.com',
...     skype_name='ivan.ivanov',
...     birthday=datetime.date(1980, 10, 21),
...     background='some background here',
...     job_title='CEO',
...     tag_list=['vip', 'online'],
...     is_company=False,
...     address_attributes={'street1': 'foo', 'street2': 'bar', 'city': 'Moscow', 'postcode': '111111', 'country_code': 'RU'},
...     custom_fields=[{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}],
...     visibility=0,
...     avatar={'path': '/absolute/path/to/file.jpg'}
... )
>>> contact
<redminelib.resources.Contact #12345 "Ivan Ivanov">

Delete methods

delete

redminelib.managers.ResourceManager.delete(resource_id)

Deletes single Contact resource from the CRM plugin by its id.

Parameters:

resource_id (int) – (required). Contact id.

Returns:

True

>>> redmine.contact.delete(1)
True

redminelib.resources.Contact.delete()

Deletes current Contact resource object from the CRM plugin.

Returns:

True

>>> contact = redmine.contact.get(1)
>>> contact.delete()
True

Export

Added in version 2.0.0.

redminelib.resources.Contact.export(fmt, savepath=None, filename=None)

Exports Contact resource in one of the following formats: atom, vcf

Parameters:

• fmt (string) – (required). Format to use for export.

• savepath (string) – (optional). Path where to save the file.

• filename (string) – (optional). Name that will be used for the file.

Returns:

String or Object

>>> contact = redmine.contact.get(123)
>>> contact.export('pdf', savepath='/home/jsmith')
'/home/jsmith/123.pdf'

redminelib.resultsets.ResourceSet.export(fmt, savepath=None, filename=None)

Exports a resource set of Contact resources in one of the following formats: atom, csv, vcf, xls

Parameters:

• fmt (string) – (required). Format to use for export.

• savepath (string) – (optional). Path where to save the file.

• filename (string) – (optional). Name that will be used for the file.

Returns:

String or Object

>>> contacts = redmine.contact.all()
>>> contacts.export('csv', savepath='/home/jsmith', filename='contacts.csv')
'/home/jsmith/contacts.csv'

Projects

Python-Redmine provides 2 methods to work with contact projects:

add

redminelib.resources.Contact.Project.add(project_id)

Adds project to contact’s project list.

Parameters:

project_id (int or string) – (required). Id or identifier of a project.

Returns:

True

>>> contact = redmine.contact.get(1)
>>> contact.project.add('vacation')
True

remove

redminelib.resources.Contact.Project.remove(project_id)

Removes project from contact’s project list.

Parameters:

project_id (int or string) – (required). Id or identifier of a project.

Returns:

True

>>> contact = redmine.contact.get(1)
>>> contact.project.remove('vacation')
True