Order

Added in version 2.5.0.

Requires Pro Edition and Products plugin >= 2.1.5.

Manager

All operations on the Order resource are provided by its manager. To get access to it you have to call redmine.order 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 Order resource with given fields and saves it to the Products plugin.

Parameters:

  • number (string) – (required). Order number.

  • project_id (int) – (required). Order project id.

  • status_id (int) – (required). Order status id.

  • order_date (string or datetime object) – (required). Date and time of the order.

  • subject (string) – (optional). Order subject.

  • contact_id (int) – (optional). Order contact id.

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

  • currency (string) – (optional). Order currency.

  • description (string) – (optional). Order description.

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

  • lines_attributes (list) – (optional). Order lines as [{'': ''}, ...], accepted keys are:

    • position (optional). Position of the line among other order lines.

    • product_id (optional). ID of the product.

    • description (required). Product description.

    • quantity (optional). Product quantity.

    • price (optional). Price of the product.

    • tax (optional). Tax in percentage.

    • discount (optional). Discount in percentage.

  • uploads (list) – (optional). Uploads as [{'': ''}, ...], accepted keys are:

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

    • filename (optional). Name of the file after upload.

    • description (optional). Description of the file.

    • content_type (optional). Content type of the file.

Returns:

Resource object

>>> order = redmine.order.create(
...     number='O-001',
...     project_id=12,
...     status_id=1,
...     order_date='2023-01-11',
...     subject='order subject',
...     contact_id=3,
...     assigned_to_id=12,
...     currency='USD',
...     description='order description',
...     lines_attributes=[{'position': 1, 'quantity': '3', 'description': 'product description', 'product_id': 1, 'tax': '10', 'price': '5', 'discount': '2'}],
...     custom_fields=[{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}],
...     uploads=[{'path': '/absolute/path/to/file'}, {'path': BytesIO(b'I am content of file 2')}]
... )
>>> order
<redminelib.resources.Order #123>

new

redminelib.managers.ResourceManager.new()

Creates new empty Order resource, but saves it to the Products 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

>>> order = redmine.order.new()
>>> order.number = 'O-001'
>>> order.project_id = 12
>>> order.status_id = 1
>>> order.order_date = '2023-01-11'
>>> order.subject = 'order subject'
>>> order.contact_id = 3
>>> order.assigned_to_id = 12
>>> order.currency = 'USD'
>>> order.description = 'order description'
>>> order.lines_attributes = [{'position': 1, 'quantity': '3', 'description': 'product description', 'product_id': 1, 'tax': '10', 'price': '5', 'discount': '2'}]
>>> order.custom_fields = [{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}]
>>> order.uploads = [{'path': '/absolute/path/to/file'}, {'path': BytesIO(b'I am content of file 2')}]
>>> order.save()
<redminelib.resources.Order #123>

Read methods

get

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

Returns single Order resource from the Products plugin by its id.

Parameters:

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

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

    • lines

Returns:

Resource object

>>> order = redmine.order.get(123, include=['lines'])
>>> order
<redminelib.resources.Order #123>

Hint

Order resource object provides you with on demand includes. On demand includes are the other resource objects wrapped in a ResourceSet which are associated with an Order 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 Order resource object are the same as in the get() method above:

>>> order = redmine.order.get(123)
>>> order.lines

all

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

Returns all Order resources from the Products plugin.

Parameters:

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

    • lines

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

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

Returns:

ResourceSet object

>>> orders = redmine.order.all(limit=50, include=['lines'])
>>> orders
<redminelib.resultsets.ResourceSet object with Order resources>

filter

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

Returns Order resources that match the given lookup parameters.

Parameters:

  • project_id (int) – (optional). Get orders for the given project id.

  • assigned_to_id (int) – (optional). Get orders which are assigned to this user id.

  • status_id (int) – (optional). Get orders which have this status id.

  • contact_id (int) – (optional). Get orders for the given contact id.

  • author_id (int) – (optional). Get orders created by given author id.

  • number (string) – (optional). Get orders for the given number.

  • amount (string) – (optional). Get orders which have given amount.

  • completed_date (string or date object) – (optional). Get orders that should be completed by this date.

  • order_date (string or date object) – (optional). Get orders created on the given date.

  • sort (string) – (optional). Column to sort, append :desc to invert the order:

    • order_date

    • status_id

    • created_at

    • updated_at

  • search (string) – (optional). Get orders for the given search string.

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

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

Returns:

ResourceSet object

>>> orders = redmine.order.filter(project_id=12, assigned_to_id=123, status_id=1, search='SO', sort='order_date:desc')
>>> orders
<redminelib.resultsets.ResourceSet object with Order resources>

Hint

You can also get orders from a Project, User and Contact resource objects directly using orders relation:

>>> project = redmine.project.get('products')
>>> project.orders
<redminelib.resultsets.ResourceSet object with Order resources>

Update methods

update

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

Updates values of given fields of an Order resource and saves them to the Products plugin.

Parameters:

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

  • number (string) – (optional). Order number.

  • project_id (int) – (optional). Order project id.

  • status_id (int) – (optional). Order status id.

  • order_date (string or datetime object) – (optional). Date and time of the order.

  • subject (string) – (optional). Order subject.

  • contact_id (int) – (optional). Order contact id.

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

  • currency (string) – (optional). Order currency.

  • description (string) – (optional). Order description.

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

  • lines_attributes (list) – (optional). Order lines as [{'': ''}, ...], accepted keys are:

    • id (optional). If not set, a new line will be created.

    • position (optional). Position of the line among other order lines.

    • product_id (optional). ID of the product.

    • description (optional). Product description.

    • quantity (optional). Product quantity.

    • price (optional). Price of the product.

    • tax (optional). Tax in percentage.

    • discount (optional). Discount in percentage.

    • _destroy (optional). Whether to delete line with a specified id.

  • uploads (list) – (optional). Uploads as [{'': ''}, ...], accepted keys are:

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

    • filename (optional). Name of the file after upload.

    • description (optional). Description of the file.

    • content_type (optional). Content type of the file.

Returns:

True

>>> redmine.order.update(
...     123,
...     number='O-001',
...     project_id=12,
...     status_id=1,
...     order_date='2023-01-11',
...     subject='order subject',
...     contact_id=3,
...     assigned_to_id=12,
...     currency='USD',
...     description='order description',
...     lines_attributes=[{'id': 1, '_destroy': True}, {'position': 1, 'quantity': '3', 'description': 'product description', 'product_id': 1, 'tax': '10', 'price': '5', 'discount': '2'}],
...     custom_fields=[{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}],
...     uploads=[{'path': '/absolute/path/to/file'}, {'path': BytesIO(b'I am content of file 2')}]
... )
True

save

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

Saves the current state of an Order resource to the Products plugin. Attrs that can be changed are the same as for update() method above.

Returns:

Resource object

>>> order = redmine.order.get(123)
>>> order.number = 'O-001'
>>> order.project_id = 12
>>> order.status_id = 1
>>> order.order_date = '2023-01-11'
>>> order.subject = 'order subject'
>>> order.contact_id = 3
>>> order.assigned_to_id = 12
>>> order.currency = 'USD'
>>> order.description = 'order description'
>>> order.lines_attributes = [{'id': 1, '_destroy': True}, {'position': 1, 'quantity': '3', 'description': 'product description', 'product_id': 1, 'tax': '10', 'price': '5', 'discount': '2'}]
>>> order.custom_fields = [{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}]
>>> order.uploads = [{'path': '/absolute/path/to/file'}, {'path': BytesIO(b'I am content of file 2')}]
>>> order.save()
<redminelib.resources.Order #123>

Added in version 2.1.0: Alternative syntax was introduced.

>>> order = redmine.order.get(123).save(
...     number='O-001',
...     project_id=12,
...     status_id=1,
...     order_date='2023-01-11',
...     subject='order subject',
...     contact_id=3,
...     assigned_to_id=12,
...     currency='USD',
...     description='order description',
...     lines_attributes=[{'id': 1, '_destroy': True}, {'position': 1, 'quantity': '3', 'description': 'product description', 'product_id': 1, 'tax': '10', 'price': '5', 'discount': '2'}],
...     custom_fields=[{'id': 1, 'value': 'foo'}, {'id': 2, 'value': 'bar'}],
...     uploads=[{'path': '/absolute/path/to/file'}, {'path': BytesIO(b'I am content of file 2')}]
... )
>>> order
<redminelib.resources.Order #123>

Delete methods

delete

redminelib.managers.ResourceManager.delete(resource_id)

Deletes single Order resource from the Products plugin by its id.

Parameters:

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

Returns:

True

>>> redmine.order.delete(123)
True
redminelib.resources.Order.delete()

Deletes current Order resource object from the Products plugin.

Returns:

True

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

Export

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

Exports a resource set of Order resources in one of the following formats: csv

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

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