Opentaps Wiki - User contributions [en]

CRM-2 Social API

2015-04-07T07:11:28Z

Jwickers:

The social API allows you to record social interactions of your customers, such as views, likes (faves), votes for and against, and comments. They can be related to other activities or to other nodes, such as web pages or blog posts. The API does not include the user interface but is meant to be called from the user interface to record the interactions.

=== Summary ===

Gets the summary of social activities that were applied to a given activity.

Method: GET, URL extension: <tt>/social/activities/:parentNoteId</tt>

Parameters:
* parentNoteId : id of the activity for which to get the summary

Returns a JSON structure with:
* thumbsUp: number of thumbs-up
* thumbsDown: number of thumbs-down
* views: number of views
* likes: number of likes
* comments: number of comments
* hasThumbUp: boolean flag indicating if the given user has thumb-up that activity
* hasThumbDown: same with thumb-down
* hasView: same with view
* hasLike: same with like
* hasComment: boolean flag indicating if the given user has commented on that activity

=== Thumbs Up ===

Records or retrieves the number of times the activity has been thumbed up.

Method: POST, URL extension: <tt>/social/thumb-up</tt>

Parameters:
* parentNoteId : id of the activity for which to record a thumb up
* userId : id of the user that thumbed the activity

=== Thumbs Down ===

Records or retrieves the number of times the activity has been thumbed down.

Method: POST, URL extension: <tt>/social/thumb-down</tt>

Parameters:
* parentNoteId : id of the activity for which to record a thumb down
* userId : id of the user that thumbed the activity

=== Views ===

Records or retrieves the number of times the activity has been viewed.

Method: POST, URL extension: <tt>/social/view</tt>

Parameters:
* parentNoteId : id of the activity for which to record a view
* userId : id of the user that viewed the activity

=== Like ===

Records or retrieves the likes or faves of an activity.

Method: POST, URL extension: <tt>/social/like</tt>

Parameters:
* parentNoteId : id of the activity for which to record a like
* userId : id of the user that viewed the activity

=== Comments ===

Records comments. A comment is first created in the pending state and will be emailed to the domain administrator (user with DOMAIN_CONF permission), who needs to approve or reject the comment. Only approved comments will be retrieved for display.

==== Posting comments ====

Method: POST, URL extension: <tt>/social/comment</tt>

Parameters:
* parentNoteId : id of the activity for which to record a comment
* userId : id of the user that commented
* noteText : the text of the comment

Comments are pending moderation, the next method is to manage that.

==== Moderating comments ====

Method: POST or GET, URL extension: <tt>/social/comment/:_id/:action</tt>

Parameters:
* _id : id of the comment
* action : either "accept" or "reject"

With "accept" the comment becomes accepted and visible by all the users, "reject" rejects the comment and it stays invisible.

==== Retreiving comments ====

Method: GET, URL extension: <tt>/social/comments/:parentNoteId</tt>

Parameters:
* parentNoteId : id of the activity for which to get the comments

Returns a JSON array of comment activities.

CRM-2 Social API

2015-03-20T07:41:57Z

Jwickers:

The social API allows you to record social interactions of your customers, such as views, likes (faves), votes for and against, and comments. They can be related to other activities or to other nodes, such as web pages or blog posts. The API does not include the user interface but is meant to be called from the user interface to record the interactions.

=== Summary ===

Gets the summary of social activities that were applied to a given activity.

Method: GET, URL extension: <tt>/social/activities/:parentNoteId</tt>

Parameters:
* parentNoteId : id of the activity for which to get the summary

Returns a JSON structure with:
* thumbsUp: number of thumbs-up
* thumbsDown: number of thumbs-down
* views: number of views
* likes: number of likes
* comments: number of comments
* hasThumbUp: boolean flag indicating if the given user has thumb-up that activity
* hasThumbDown: same with thumb-down
* hasView: same with view
* hasLike: same with like
* hasComment: boolean flag indicating if the given user has commented on that activity

=== Views ===

Records or retrieves the number of times the activity has been viewed.

Method: POST, URL extension: <tt>/social/view</tt>

Parameters:
* parentNoteId : id of the activity for which to record a view
* userId : id of the user that viewed the activity

=== Like ===

Records or retrieves the likes or faves of an activity.

Method: POST, URL extension: <tt>/social/like</tt>

Parameters:
* parentNoteId : id of the activity for which to record a like
* userId : id of the user that viewed the activity

=== Comments ===

Records comments. A comment is first created in the pending state and will be emailed to the domain administrator (user with DOMAIN_CONF permission), who needs to approve or reject the comment. Only approved comments will be retrieved for display.

==== Posting comments ====

Method: POST, URL extension: <tt>/social/comment</tt>

Parameters:
* parentNoteId : id of the activity for which to record a comment
* userId : id of the user that commented
* noteText : the text of the comment

Comments are pending moderation, the next method is to manage that.

==== Moderating comments ====

Method: POST or GET, URL extension: <tt>/social/comment/:_id/:action</tt>

Parameters:
* _id : id of the comment
* action : either "accept" or "reject"

With "accept" the comment becomes accepted and visible by all the users, "reject" rejects the comment and it stays invisible.

==== Retreiving comments ====

Method: GET, URL extension: <tt>/social/comments/:parentNoteId</tt>

Parameters:
* parentNoteId : id of the activity for which to get the comments

Returns a JSON array of comment activities.

CRM-2 Social API

2015-03-20T07:40:46Z

Jwickers: /* Thumb Up and Thumb Down */

The social API allows you to record social interactions of your customers, such as views, likes (faves), votes for and against, and comments. They can be related to other activities or to other nodes, such as web pages or blog posts. The API does not include the user interface but is meant to be called from the user interface to record the interactions.

=== Summary ===

Gets the summary of social activities that were applied to a given activity.

Method: GET, URL extension: <tt>/social/activities/:parentNoteId</tt>

Parameters:
* parentNoteId : id of the activity for which to get the summary

Returns JSON structure with:
* thumbsUp: number of thumbs-up
* thumbsDown: number of thumbs-down
* views: number of views
* likes: number of likes
* comments: number of comments
* hasThumbUp: boolean flag indicating if the given user has thumb-up that activity
* hasThumbDown: same with thumb-down
* hasView: same with view
* hasLike: same with like
* hasComment: boolean flag indicating if the given user has commented on that activity

=== Views ===

Records or retrieves the number of times the activity has been viewed.

Method: POST, URL extension: <tt>/social/view</tt>

Parameters:
* parentNoteId : id of the activity for which to record a view
* userId : id of the user that viewed the activity

=== Like ===

Records or retrieves the likes or faves of an activity.

Method: POST, URL extension: <tt>/social/like</tt>

Parameters:
* parentNoteId : id of the activity for which to record a like
* userId : id of the user that viewed the activity

=== Comments ===

Records comments. A comment is first created in the pending state and will be emailed to the domain administrator (user with DOMAIN_CONF permission), who needs to approve or reject the comment. Only approved comments will be retrieved for display.

==== Posting comments ====

Method: POST, URL extension: <tt>/social/comment</tt>

Parameters:
* parentNoteId : id of the activity for which to record a comment
* userId : id of the user that commented
* noteText : the text of the comment

Comments are pending moderation, the next method is to manage that.

==== Moderating comments ====

Method: POST or GET, URL extension: <tt>/social/comment/:_id/:action</tt>

Parameters:
* _id : id of the comment
* action : either "accept" or "reject"

With "accept" the comment becomes accepted and visible by all the users, "reject" rejects the comment and it stays invisible.

==== Retreiving comments ====

Method: GET, URL extension: <tt>/social/comments/:parentNoteId</tt>

Parameters:
* parentNoteId : id of the activity for which to get the comments

=== Comments ===

Records comments. A comment is first created in the pending state and will be emailed to the domain administrator (user with DOMAIN_CONF permission), who needs to approve or reject the comment. Only approved comments will be retrieved for display.

CRM-2 Social API

2015-03-20T07:39:43Z

Jwickers:

The social API allows you to record social interactions of your customers, such as views, likes (faves), votes for and against, and comments. They can be related to other activities or to other nodes, such as web pages or blog posts. The API does not include the user interface but is meant to be called from the user interface to record the interactions.

=== Summary ===

Gets the summary of social activities that were applied to a given activity.

Method: GET, URL extension: <tt>/social/activities/:parentNoteId</tt>

Parameters:
* parentNoteId : id of the activity for which to get the summary

Returns JSON structure with:
* thumbsUp: number of thumbs-up
* thumbsDown: number of thumbs-down
* views: number of views
* likes: number of likes
* comments: number of comments
* hasThumbUp: boolean flag indicating if the given user has thumb-up that activity
* hasThumbDown: same with thumb-down
* hasView: same with view
* hasLike: same with like
* hasComment: boolean flag indicating if the given user has commented on that activity

=== Views ===

Records or retrieves the number of times the activity has been viewed.

Method: POST, URL extension: <tt>/social/view</tt>

Parameters:
* parentNoteId : id of the activity for which to record a view
* userId : id of the user that viewed the activity

=== Like ===

Records or retrieves the likes or faves of an activity.

Method: POST, URL extension: <tt>/social/like</tt>

Parameters:
* parentNoteId : id of the activity for which to record a like
* userId : id of the user that viewed the activity

=== Thumb Up and Thumb Down ===

Records and retrieves votes either for or against.

Method: POST, URL extension: <tt>/social/thumb-up</tt>
Method: POST, URL extension: <tt>/social/thumb-down</tt>

Parameters:
* parentNoteId : id of the activity for which to record a thumb-up or thumb-down
* userId : id of the user that voted on the activity

Note: only one of those action is active for a given user and activity, if the user thumb-up then thumb-down his thumb-up is deleted.

=== Comments ===

Records comments. A comment is first created in the pending state and will be emailed to the domain administrator (user with DOMAIN_CONF permission), who needs to approve or reject the comment. Only approved comments will be retrieved for display.

CRM-2 Social API

2015-03-20T07:35:33Z

Jwickers: /* Comments */

The social API allows you to record social interactions of your customers, such as views, likes (faves), votes for and against, and comments. They can be related to other activities or to other nodes, such as web pages or blog posts. The API does not include the user interface but is meant to be called from the user interface to record the interactions.

=== Views ===

Records or retrieves the number of times the activity has been viewed.

Method: POST, URL extension: <tt>/social/view</tt>

Parameters:
* parentNoteId : id of the activity for which to record a view
* userId : id of the user that viewed the activity

=== Like ===

Records or retrieves the likes or faves of an activity.

Method: POST, URL extension: <tt>/social/like</tt>

Parameters:
* parentNoteId : id of the activity for which to record a like
* userId : id of the user that viewed the activity

=== Thumb Up and Thumb Down ===

Records and retrieves votes either for or against.

Method: POST, URL extension: <tt>/social/thumb-up</tt>
Method: POST, URL extension: <tt>/social/thumb-down</tt>

Parameters:
* parentNoteId : id of the activity for which to record a thumb-up or thumb-down
* userId : id of the user that voted on the activity

Note: only one of those action is active for a given user and activity, if the user thumb-up then thumb-down his thumb-up is deleted.

=== Comments ===

Records comments. A comment is first created in the pending state and will be emailed to the domain administrator (user with DOMAIN_CONF permission), who needs to approve or reject the comment. Only approved comments will be retrieved for display.

==== Posting comments ====

Method: POST, URL extension: <tt>/social/comment</tt>

Parameters:
* parentNoteId : id of the activity for which to record a comment
* userId : id of the user that commented
* noteText : the text of the comment

Comments are pending moderation, the next method is to manage that.

==== Moderating comments ====

Method: POST or GET, URL extension: <tt>/social/comment/:_id/:action</tt>

Parameters:
* _id : id of the comment
* action : either "accept" or "reject"

With "accept" the comment becomes accepted and visible by all the users, "reject" rejects the comment and it stays invisible.

==== Retreiving comments ====

Method: GET, URL extension: <tt>/comments/:parentNoteId</tt>

Parameters:
* parentNoteId : id of the activity for which to get the comments

CRM-2 Social API

2015-03-20T07:31:56Z

Jwickers: /* Thumb Up and Thumb Down */

CRM-2 Social API

2015-03-20T07:27:12Z

Jwickers: /* Thumb Up and Thumb Down */

CRM-2 Social API

2015-03-20T07:26:52Z

Jwickers: /* Like */

CRM-2 Social API

2015-03-20T07:26:33Z

Jwickers: /* Thumb Up and Thumb Down */

CRM-2 Social API

2015-03-20T07:24:59Z

Jwickers: /* Like */

CRM-2 Social API

2015-03-20T07:24:30Z

Jwickers: /* Views */

CRM-2 Administrative API

2014-10-15T06:36:42Z

Jwickers: /* Email Notifications */

Administrative API is used to manage your domain.

The API calls follow the general RESTful pattern of [[CRM-2 API]]. The base URL is <tt>https://crm2.opentaps.com/admin/</tt>

To access the admin API, your user must have the '''DOMAIN_CONF''' permission.

For all requests the clientDomain and authToken parameters are required.

Here are the additional resources available:

=== Reset (Permanent) Token ===

Method: POST
URL extension: <tt>/admin/reset-token</tt>
Parameter:
* Current permanent auth token for your user
* Client domain

This API expires (deletes) the current permanent auth token, generates a new one, and returns it to you as the result. After this, you must use the new one to access the system. The API will validate that the token you've supplied is for a user of your domain.

=== Users ===

Add or remove users for a Contact

URL extension: <tt>/admin/user</tt>

Parameters:
* contactId : unique ID of your Contact
* userId: id of user. For Gmail, use full email (someone@gmail.com). For twitter, use username without the initial @ (someone)
* userIdType: type of your user id. Use GOOGLE_APPS for Gmail or TWITTER_LOGIN for Twitter.

Add a new User and Contact at the same time with

URL extension: <tt>/admin/user-contact</tt>

Parameters:
* firstName
* lastName
* companyName
* emailAddress
* userId
* userIdType: Same as above

=== User Permissions ===

Add or remove a security permission from a user

URL extension: <tt>/admin/user-permission</tt>

Parameters:
* userId: unique id of the user
* permission: Permission string

If the permission you are trying to add is not a valid permission, you will get an error message with a list of the valid permissions.

Valid permissions are:
* CONTACT_VIEW - view contacts and contact groups
* CONTACT_UPDATE - create, update, delete contacts and contact groups
* ACTIVITY_VIEW - view activities, such as tasks
* ACTIVITY_UPDATE - create, update, delete activities
* DOMAIN_CONF - administer the domain.

=== Email Notifications ===

Configure the email account to use when sending notification emails for your domain. You must also configure the same email as an email to poll (see below) separately so that the responses are also registered. Otherwise, response to your notification emails will be ignored.

URL extension: <tt>/admin/email-notifications</tt> (ie, <tt>https://crm2.opentaps.com/admin/email-notifications</tt>)

Parameters are the ones for your mail server, ie <tt>mailUser</tt>, <tt>mailPass</tt>, <tt>mailStoreProtocol</tt>, <tt>mailHost</tt>. For gmail, use <tt>smtp</tt> and <tt>smtp.gmail.com</tt> for protocol and host. Note: do not try to use smtps which is not a valid transport, the code will connect using SSL on port 465 automatically.

For all requests the clientDomain and authToken parameters are required.

* The method POST and PUT is used to SET the email notification account settings.
* The method DELETE is used to REMOVE the email notification account settings.
* The method GET is used to GET the current email notification account settings.

Note: the password is encrypted in the DB and won't be returned in the replies.

=== Emails To Poll ===

Configures the emails to be polled for your domain.

URL extension: <tt>/admin/email-to-poll</tt> (ie, <tt>https://crm2.opentaps.com/admin/email-to-poll</tt>)

Parameters are the ones for your mail server, ie <tt>mailUser</tt>, <tt>mailPass</tt>, <tt>mailStoreProtocol</tt>, <tt>mailHost</tt>. For gmail, use <tt>gimap</tt> and <tt>pop.googlemail.com</tt> for protocol and host.

* The method POST is used to ADD email to poll.
* The method PUT is used to UPDATE email to poll.
* The method DELETE is used to REMOVE email to poll.
* The method GET is used to GET list of the emails to poll.

For POST, PUT and DELETE, mailUser is required.

Note: the password is encrypted in the DB and won't be returned in the replies.

=== Valid Activity Types ===

Configures the valid activity types for your domain's application settings. Activity types are always capitalized and automatically capitalized when you add them.

URL: <tt>https://crm2.opentaps.com/admin/activity-type</tt>

* POST adds a single activityType
* GET returns a list of valid activity types
* DELETE removes a single activityType

=== Twitter ===

Configures the twitter users which opentaps CRM2 uses to interact with twitter. Normally this is done automatically when somebody logs into twitter.com once from the login page, but you can control it more explicitly using this API to add a user or remove one that you don't want to use.

URL: <tt>https://crm2.opentaps.com/admin/twitter</tt>

* POST adds a new user to use with twitter. Parameters are <tt>userName</tt>, <tt>userId</tt>, <tt>token</tt>, and <tt>tokenSecret</tt>
* GET returns a list of users to use with twitter
* DELETE removes a user. Parameter is <tt>userName</tt>

CRM-2 Administrative API

2013-07-02T06:57:23Z

Jwickers:

Administrative API is used to manage your domain.

The API calls follow the general RESTful pattern of [[CRM-2 API]]. The base URL is <tt>http://crm-2-url/admin/</tt>

To access the admin API, your user must have the '''DOMAIN_CONF''' permission.

Here are the additional resources available:

=== Email Notifications ===

Configure the email account to use when sending notification emails for your domain.

URL extension: <tt>/admin/email-notifications</tt> (ie, <tt>http://crm-2-url/admin/email-notifications</tt>)

Parameters are the ones for your mail server, ie <tt>mailUser</tt>, <tt>mailPass</tt>, <tt>mailStoreProtocol</tt>, <tt>mailHost</tt>. For gmail, use <tt>smtps</tt> and <tt>smtp.google.com</tt> for protocol and host.

For all requests the clientDomain and authToken parameters are required.

* The method POST and PUT is used to SET the email notification account settings.
* The method DELETE is used to REMOVE the email notification account settings.
* The method GET is used to GET the current email notification account settings.

Note: the password is encrypted in the DB and won't be returned in the replies.

=== Emails To Poll ===

Configures the emails to be polled for your domain.

URL extension: <tt>/admin/email-to-poll</tt> (ie, <tt>http://crm-2-url/admin/email-to-poll</tt>)

Parameters are the ones for your mail server, ie <tt>mailUser</tt>, <tt>mailPass</tt>, <tt>mailStoreProtocol</tt>, <tt>mailHost</tt>. For gmail, use <tt>imaps</tt> and <tt>pop.google.com</tt> for protocol and host.

For all requests the clientDomain and authToken parameters are required.

* The method POST is used to ADD email to poll.
* The method PUT is used to UPDATE email to poll.
* The method DELETE is used to REMOVE email to poll.
* The method GET is used to GET list of the emails to poll.

For POST, PUT and DELETE, mailUser is required.

Note: the password is encrypted in the DB and won't be returned in the replies.

=== Valid Activity Types ===

Configures the valid activity types for your domain's application settings. Activity types are always capitalized and automatically capitalized when you add them.

URL extension: <tt>/admin/activity-type</tt> (ie, <tt>http://crm-2-url/admin/activity-type</tt>)

* POST adds a single activityType
* GET returns a list of valid activity types
* DELETE removes a single activityType

CRM-2 Contacts API

2013-04-11T14:06:44Z

Jwickers:

== Contacts API is used to create and retreive contacts. ==

The API calls follow the general RESTful pattern of [[CRM-2 API]].

The base URL is <tt>http://crm-2-url/crm2/contact</tt>

=== GET: Get a List of Contacts ===
* contactId
* emailAddress
* attribute Map

=== POST: Create a contact ===
* firstName
* lastName
* companyName
* emailsNumber (used to iterate the following parameter where N is an index number)
** emailN (the email address)
** emailPurposeN (can be one of : PRIMARY, OTHER, ORDER, BILLING_AR, PAYMENT_AR, SHIPMENT)
* attribute Map (described as a series of <tt>attribute_${key}=${value}</tt> parameters)

The operation returns a JSON response with the created contact eg:
{"result":{"resultValue":{"contactId":"5166b967e4b0f6e6cd09e653","firstName":"test","clientDomain":"mydomain.com","emails":[{"email":"test@example.com","purpose":"PRIMARY"}],"attributes":{"somekey":"somevalue"}}}}

=== PUT: Update a contact ===
* firstName
* lastName
* companyName
* emailsNumber (used to iterate the following parameter where N is an index number)
** emailN (the email address)
** emailPurposeN (can be one of : PRIMARY, OTHER, ORDER, BILLING_AR, PAYMENT_AR, SHIPMENT)
* attribute Map (described as a series of <tt>attribute_${key}=${value}</tt> parameters)

Note that when updating:
* the attributes are always overwritten so not gving any attribute will remove the existing ones
* emails are only overwritten if at least one email is given or emailsNumber is set to 0 in which case the existing ones will be removed
* firstName, lastName, companyName are only updated when given, they must be given and set to an empty value to be removed

The operation returns a JSON response with the new values of the updated contact eg:
{"result":{"resultValue":{"contactId":"5166b967e4b0f6e6cd09e653","firstName":"test","clientDomain":"mydomain.com","emails":[{"email":"test@example.com","purpose":"PRIMARY"}],"attributes":{"somekey":"somevalue"}}}}

== Import Contact API ==

A similar API is available to easily import contacts, it only allows POST operations but will create the contacts or update if one is found matching the given attributes.

The base URL is <tt>http://crm-2-url/crm2/contact-import</tt>

=== POST: Create or update Contact ===
* firstName
* lastName
* companyName
* emailsNumber (used to iterate the following parameter where N is an index number)
** emailN (the email address)
** emailPurposeN (can be one of : PRIMARY, OTHER, ORDER, BILLING_AR, PAYMENT_AR, SHIPMENT)
* attribute Map (described as a series of <tt>attribute_${key}=${value}</tt> parameters)

Only the attributes given as attribute_XXX are used to find an existing contact for update, if they are not given and / or a contact matching those is not found the operation will create a new contact.

The operation returns a JSON response with the contact ID of the created or updated record, eg:
{ "contact": { "contactId": XXX } }

The attribute Map is described as a series of <tt>attribute_${key}=${value}</tt> parameters. For example, attribute_opentapsPartyId=12345 will become {opentapsPartyId:12345}

CRM-2 Contacts API

2013-04-03T08:30:25Z

Jwickers: Protected "CRM-2 Contacts API": Sysop page [edit=sysop:move=sysop]

Contacts API is used to create and retreive contacts.

The API calls follow the general RESTful pattern of [[CRM-2 API]].

The base URL is <tt>http://crm-2-url/crm2/contact</tt> , only POST is currently supported, which is used to create or update a contact.

The following parameters are supported:
* firstName
* lastName
* companyName
* emailsNumber (used to iterate the following parameter where N is an index number)
** emailN (the email address)
** emailPurposeN (can be one of : PRIMARY, OTHER, ORDER, BILLING_AR, PAYMENT_AR, SHIPMENT)
* attribute_XXX (can define additional attributes where XXX is the attribute name)

Only the attributes given as attribute_XXX are used to find an existing contact for update, if they are not given and / or a contact matching those is not found the operation will create a new contact.

The operation returns a JSON response with the contact ID of the created or updated record, eg:
{ "contact": { "contactId": XXX } }

CRM-2 Contacts API

2013-04-03T08:30:24Z

Jwickers: New page: Contacts API is used to create and retreive contacts. The API calls follow the general RESTful pattern of CRM-2 API. The base URL is <tt>http://crm-2-url/crm2/contact</tt> , only POS...

CRM-2 Administrative API

2013-04-03T07:49:52Z

Jwickers:

Managing Fixed Assets

2012-06-26T07:39:54Z

Jwickers: /* Using Fixed Assets Management */

===Using Fixed Assets Management===
To access the Fixed Assets management screens, proceed as follows from the
Main Navigation screen (flash page):
Click: [Catalog Manager] Icon > [Home] drop down button > [Asset Maint] link,
Click: [Asset Maintenance Application] drop down button > [Fixed Assets] link,
The "Find Fixed Assets" page opens.

Or in the accounting application, then the Fixed Assets tab. eg: on a local instance the link would be http://127.0.0.1:8080/accounting/control/ListFixedAssets

Managing Fixed Assets

2012-06-26T07:39:16Z

Jwickers: /* Using Fixed Assets Management */

Opentaps 2 Service Validation

2012-01-30T14:50:21Z

Jwickers: New page: There are currently two level of validations, one at the service level which validates the parameters given, and one at the persistence level. == General Concept == Validation at those l...

There are currently two level of validations, one at the service level which validates the parameters given, and one at the persistence level.

== General Concept ==

Validation at those levels is implemented using Bean Validation (JSR-303), which simply consist of annotations on a POJO's properties or accessors. There are numerous online articles to learn more about it, eg: http://java.dzone.com/articles/bean-validation-made-simple

Some validators are quite simple, like ''javax.validation.constraints.NotNull'', and it is also very easy to define your own, like for example ''org.opentaps.validation.contraints.NotEmpty''.

A Validator can also be set on a class itself when complex validation involving multiple properties is needed.

== Validation on Entities ==

JPA supports Bean Validation internally so an entity which is annotated will only be persisted if it is valid.

== Validation in the Services ==

Validation in the Services is done in a similar manner, the Input and Output objects are annotated and the service implementation is responsible for calling the validator.

For this the ''validation.api'' bundle defines a ''ValidationService'' which is provided by the ''validation.impl'' bundle which itself simply expose the implementation given by Geronimo.

A typical pattern in the service implementation can be seen in ''org.opentaps.notes.services.impl.CreateNoteServiceImpl'' and is basically:

Set<ConstraintViolation<MyServiceInput>> inputViolations = validationService.getValidator().validate(input);
if (inputViolations.size() > 0) {
throw new ServiceValidationException("My service failed.", (Set) inputViolations);
}

try {
// do something involving persistence
...
} catch (ConstraintViolationException e) {
throw new ServiceValidationException("My service failed.", e);
} catch (PersistenceException e) {
throw new ServiceException("My service failed.", e);
}

// populate the output
MyServiceOutput out = new MyServiceOutput();
...

Set<ConstraintViolation<MyServiceOutput>> outputViolations = validationService.getValidator().validate(out);
if (outputViolations.size() > 0) {
throw new ServiceValidationException("My service failed.", (Set) outputViolations);
}

== Sending Validation Errors to the Client ==

As an example the Note rest service `org.opentaps.notes.rest.NoteResource` simply extends `org.opentaps.rest.ServerResource` which implements an exception handler that translates a `ServiceValidationException` into a JSON structure.

Part of the JSON response includes a `errorDetail` object which is an array of `ServiceValidationException.FieldError` which contains 3 fields:
* ''field'' which is the field name in the service interface that was not valid
* ''message'' which is the error message returned by the validator
* ''value'' which was the value given that failed validation

The client can then read that response to present the errors to the user.

Opentaps 2 Service Validation

2012-01-30T14:50:21Z

Jwickers: Protected "Opentaps 2 Service Validation": Sysop page [edit=sysop:move=sysop]

Opentaps 2 Automated Testing

2012-01-26T07:35:12Z

Jwickers: /* opentaps 2 Automated Testing */

== opentaps 2 Automated Testing ==

opentaps 2 supports both unit and automated testing.

=== Running the tests ===

To run unit tests:

mvn -DskipTests=false verify

To run integration tests:

mvn -Dit verify

To run both:

mvn -DskipTests=false -Dit verify

Also when running unit tests one can chose to run only one test, for example:

mvn verify -DskipTests=false -Dtest=ValidationTest

where -Dtest=<name of the unit test classes (can be comma separated)>

=== Checking the tests results ===

Integration tests results can be checked in the maven output, but also each test output and the tests summary can be found at

./integration-tests/tests-run/target/failsafe-reports/

For unit tests, the output can be found for each module, for example at

./modules/notes/impl/tests/target/surefire-reports/

=== How to setup unit tests with Pax Exam ===

Because the integration tests runs Geronimo it can take quite some time to start and run, which can be discouraging when doing TDD or simply wanting to test a particular case.

As an example, in `./modules/notes/impl/tests/` is the module containing the unit tests for the `notes` module.

First is the Pax Exam configuration class:

./modules/notes/impl/tests/src/test/java/org/opentaps/notes/tests/NotesTestConfig.java

Its role is to configure the OSGI environment in which the tests will be run by listing the bundles to be started. Some of those constitute an environment similar to what is provided by the Geronimo server : JPA, transactions, aries blueprint, apache bval, and their dependencies etc .. the others are the API and implementation bundles of the module we are testing.

Worth noting is the ''org.opentaps.validation.testimpl'' bundle which replaces ''org.opentaps.validation.impl'' during unit testing as a way to bootstrap and provide JSR303 validation.

Second are the JUnit style unit tests, they all extend the configuration class, for example:

./modules/notes/impl/tests/src/test/java/org/opentaps/notes/tests/NoteApiTest.java

The only particularities here are the ''@RunWith(JUnit4TestRunner.class)'' annotation which allows Pax Exam to run it as a JUnit unit test, and the ''@Inject'' annotations that will inject the OSGI services.

Opentaps 2 Automated Testing

2012-01-26T07:20:27Z

Jwickers: /* opentaps 2 Automated Testing */

Opentaps Analytics Data Loader

2011-04-22T11:10:28Z

Jwickers: /* ORDER_ITEM_FACT */

__TOC__

== Uploaders ==

=== opentaps and OFBiz ===
analytics-upload component help to gather and upload analytical data to server. A few steps should be done to install it with opentaps or OfBiz instance.

# Checkout component into hot-deploy. Use <code>svn co svn://svn.opentaps.org/opentaps/modules/analytics-upload/versions/1.5/trunk analytics-upload</code>
# If you are using opentaps 1.0 or 1.4, add it to your <code>hot-deploy/component-load.xml</code> file.
# Adjust settings in config/analytics-uploader.properties. Webkey should be the one for your store in opentaps Analytics.
# Note there are two ''scripts'' value in configuration file, default one to use with opentaps instance and another for OfBiz.
# Start instance and run '''analytics.uploadAnalyticalData''' service.

== API ==

Data Loading is done via an HTTP POST to <nowiki>http://analytics.opentaps.com/analytics/control/loaddata</nowiki>

The following parameter are required:
* userlogin
* password
* webkey

Your userlogin must have the ANALYTICS_DATA_LOAD permission to load data.

Then the data to load should be given as one parameter per field using the format ''idx.tablename.fieldname=value'' where ''idx'' is a string used both to order the import (if mutliple record depend on each other via a FK) and discriminate which fields are in the same DB row.

Possible HTTP error codes are:
* 400 Bad Request : missing parameter, invalid field name, bad format, no data to load
* 401 Unauthorized : authentication failed
* 404 Not Found : given webkey does not correspond to an existing Store
* 403 Forbidden : tried to modify a table or field that cannot be modified
* 409 Conflict : found the same rows defined twice
* 500 Internal error : other exception during import

To clear your data, you can send an HTTP POST to <nowiki>http://analytics.opentaps.com/analytics/control/cleardata</nowiki> with your userlogin, password, and webkey.

'''WARNING''': This REALLY will get rid of all your data.

Your userlogin must have the ANALYTICS_DATA_CLEAR permission to clear your data.

=== Examples ===

The following examples are using the curl command line utility to perform the HTTP POSTs.

Posting data in the ''CHANNEL_DIMENSION'':

curl -i -d userlogin=myuser -d password=mypass -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>https://analytics.opentaps.com/analytics/control/loaddata</nowiki>

Returned Success message would be like:

HTTP/1.1 200 OK
...
<html>
<head>
<title>Dataload: success</title>
</head>
<body class="success">
Successfully loaded 1 rows
</body>
</html>

Multiple rows can be inserted in the same request, using the IDX part to order the insertion in case a row needs to reference to a previously loaded row:

curl -i -d userlogin=myuser -d password=mypass -d webkey=thisisatest1234 \
-d "0.sales_team_dimension.sales_team_id=MY_TEAM" -d "0.sales_team_dimension.sales_team_name=My Sales Team" \
-d "1.sales_rep_dimension.sales_rep_id=MY_SALESREP" -d "1.sales_rep_dimension.sales_team_id=MY_TEAM" \
<nowiki>http://analytics.opentaps.com/analytics/control/loaddata</nowiki>

Example with bad authentication:

curl -i -d userlogin=myuser -d password=mypass -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://analytics.opentaps.com/analytics/control/loaddata</nowiki>

HTTP/1.1 401 Unauthorized
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Authentication failed.
</body>
</html>

Example of Error when trying to add data in an in-existing field:

curl -i -d userlogin=myuser -d password=mypass -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_description=My Channel" <nowiki>http://analytics.opentaps.com/analytics/control/loaddata</nowiki>

HTTP/1.1 500 Internal Server Error
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Data Load error: Error processing the SQL Query
Caused by: Unknown column 'CHANNEL_DESCRIPTION' in 'field list'
</body>
</html>

=== Data Model Reference ===

The following tables and fields can be given:

==== CHANNEL_DIMENSION ====

This dimension table is for the sales channels of your company (ie, Phone, Online, Catalog, Store.)

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CHANNEL_ID || String (60) || Unique ID of the sales channel
|-
| CHANNEL_NAME || String (100) || Descriptive name of the sales channel
|}

==== SALES_TEAM_DIMENSION ====

This dimension table is for the sales teams of your company.

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_TEAM_ID || String (60) || Unique ID of your sales team.
|-
| SALES_TEAM_NAME || String (100) || Descriptive name of your sales team.
|}

==== SALES_REP_DIMENSION ====

This dimension table is for the sales representatives of your company.

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_REP_ID || String (60) || Unique ID of a sales representative.
|-
| SALES_TEAM_ID || String (60) || ID of the sales team for the sales representative. References SALES_TEAM_DIMENSION
|-
| SALES_TEAM_NAME || String (100) || Descriptive name of the sales team.
|-
| FIRST_NAME || String (100) || First name of the sales representative
|-
| LAST_NAME || String (100) || Last name of the sales representative
|}

==== CUSTOMER_DIMENSION ====

This dimension is for your company's customers. Currently the table supports address line, so use it for the most meaningful one for your business, ie the customer's home address.

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CUSTOMER_ID || String (60) || The ID of the Customer
|-
| CUSTOMER_NAME || String (255) || The Customer name
|-
| COMPANY_NAME || String (255) || The Customer company name
|-
| INDUSTRY || String (60) || The Customer industry
|-
| FIRST_NAME || String (100) || The Customer first name
|-
| LAST_NAME || String (100) || The Customer last name
|-
| ATTN_NAME || String (100) || The address attention name
|-
| STREET_ADDRESS_LINE1 || String (255) || Street of the customer's address
|-
| CITY || String (60) || City of the customer's address
|-
| STATE || String (60) || State of the customer's address
|-
| REGION || String (60) || Region of the customer's address, if relevant
|-
| COUNTRY || String (100) || Country of the customer's address
|-
| POSTAL_CODE3DIGIT || String (3) || First 3 digits of the postal code for the customer's address
|-
| POSTAL_CODE || String (60) || Full postal code for the customer's address
|-
| PHONE_COUNTRY || String (60) || Country code of the customer's phone number
|-
| PHONE_AREA_CODE || String (60) || Area code of the customer's phone number
|-
| PHONE_NUMBER || String (60) || Remaining digits of customer's phone number
|-
| PRIMARY_EMAIL || String (255) || Customer's primary email address
|-
| OTHER_EMAIL || String (255) || Customer's other email address
|-
| CUSTOMER_TYPE || String (60) || Type for the customer. Fill in whatever you want.
|-
| SOURCE || String (60) || Source code of the Customer. Fill in whatever you want.
|-
| SALES_TEAM_NAME || String (255) || The name of Sales Team associated to the Customer, from SALES_TEAM_DIMENSION
|-
| CREATED_DATE_AND_TIME || Timestamp || Time and date when customer was first created. Format is ''YYYY-MM-DD hh:mm:ss''
|}

==== PRODUCT_DIMENSION ====

This dimension table contains the products of your company.

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| PRODUCT_ID || String (60) || Unique ID of your product
|-
| SKU || String (60) || The Product SKU code
|-
| UPC || String (60) || The Product UPC code
|-
| PRODUCT_NAME || String (100) || The Product name
|-
| BRAND || String (100) || The Product brand
|-
| CATEGORY || String (100) || The Product category name
|-
| SIZE || String (100) || The Product size
|-
| STYLE || String (100) || The Product style
|-
| COLOR || String (100) || The Product color
|-
| WIDTH || Numeric (18,6) || The Product width
|-
| LENGTH || Numeric (18,6) || The Product length
|-
| HEIGHT || Numeric (18,6) || The Product height
|-
| WEIGHT || Numeric (18,6) || The Product weight
|-
| DIAMETER || Numeric (18,6) || The Product diameter
|-
| PRODUCT_TYPE || String (100) || The Product type
|-
| SUPPLIER_NAME || String (100) || Name of the supplier for this product
|-
| ORG_SUPPLIER_ID || String (60) || ID of the supplier
|-
| EST_BASE_CURRENCY_COST || Numeric (18,6) || The Product estimated cost
|}

==== ORDER_ITEM_FACT ====

This fact table contains all the line items of your orders. It also includes any returns of the order items.

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| ORDER_ID || String (60) || ID of the order
|-
| ORDER_ITEM_SEQ_ID || String (100) || ID for the item within the order, ie 1, 2, 3, ...
|-
| CUSTOMER_ID || String (60) || The customer identifier, references the CUSTOMER_DIMENSION
|-
| CHANNEL_ID || String (60) || The channel identifier, references the CHANNEL_DIMENSION
|-
| SALES_REP_ID || String (60)|| The sales representative identifier, references the SALES_REP_DIMENSION
|-
| SALES_TEAM_ID || String (60) || The sales team identifier, references the SALES_TEAM_DIMENSION
|-
| ORDER_DATE || String (Date) || The date the order was placed, format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) || The product identifier, references the PRODUCT_DIMENSION
|-
| QUANTITY || Numeric (18,6) || The quantity of item ordered
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) || Gross amount of the order item
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) || Net amount of the order item, ie gross amount minus discount
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2)|| Amount of discount on order item
|-
| RESOLUTION_STATUS || String (25) || Status of the order item: completed, canceled, etc.
|-
| RETURNED_QUANTITY || Numeric (18,6) || The quantity of the item that was returned
|-
| RETURNED_GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) || Gross amount of return associated with order item
|-
| RETURNED_DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) || Discount on amount returned
|-
| RETURNED_NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) || Net amount of return
|}

==== RETURN_ITEM_FACT ====

This fact table is for returns.

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| RETURN_ID || String (60) || Unique ID of the return
|-
| RETURN_ITEM_SEQ_ID || String (100) || ID of the item within the return
|-
| CUSTOMER_ID || String (60) || The customer identifier, references the CUSTOMER_DIMENSION
|-
| CHANNEL_ID || String (60) || The channel identifier, references the CHANNEL_DIMENSION
|-
| ORDER_DATE || String (Date) || The date the original order was placed, format is ''YYYY-MM-DD''
|-
| RETURN_DATE || String (Date) || The date the return was performed, format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) || The product identifier, references the PRODUCT_DIMENSION
|-
| QUANTITY || Numeric (18,6) || The quantity of product returned
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) || Gross amount being returned
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) || Net amount being returned, or gross - discount
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) || Discount for the amount being returned
|-
| RESOLUTION_STATUS || String (25) || Status of the return: processed, rejected, canceled, etc.
|}

Opentaps Analytics Data Loader

2011-04-12T14:47:02Z

Jwickers: /* CUSTOMER_DIMENSION */

__TOC__

== Uploaders ==

=== opentaps and OFBiz ===
analytics-upload component help to gather and upload analytical data to server. A few steps should be done to install it with opentaps or OfBiz instance.

# Checkout component into hot-deploy. Use <code>svn co svn://svn.opentaps.org/opentaps/modules/analytics-upload/versions/1.5/trunk analytics-upload</code>
# Adjust settings in config/analytics-uploader.properties. Webkey should be the one for your store in opentaps Analytics.
# Note there are two ''scripts'' value in configuration file, default one to use with opentaps instance and another for OfBiz.
# Start instance and run '''analytics.uploadAnalyticalData''' service.

== API ==

Data Loading is done via an HTTP POST servlet.

The following parameter are required:
* userlogin
* password
* webkey

Then the data to load should be given as one parameter per field using the format ''idx.tablename.fieldname=value'' where ''idx'' is a string used both to order the import (if mutliple record depend on each other via a FK) and discriminate which fields are in the same DB row.

Possible HTTP error codes are:
* 400 Bad Request : missing parameter, invalid field name, bad format, no data to load
* 401 Unauthorized : authentication failed
* 404 Not Found : given webkey does not correspond to an existing Store
* 403 Forbidden : tried to modify a table or field that cannot be modified
* 409 Conflict : found the same rows defined twice
* 500 Internal error : other exception during import

=== Examples ===

The following examples are using the curl command line utility to perform the HTTP POSTs.

Posting data in the ''CHANNEL_DIMENSION'':

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

Returned Success message would be like:

HTTP/1.1 200 OK
...
<html>
<head>
<title>Dataload: success</title>
</head>
<body class="success">
Successfully loaded 1 rows
</body>
</html>

Multiple rows can be inserted in the same request, using the IDX part to order the insertion in case a row needs to reference to a previously loaded row:

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 \
-d "0.sales_team_dimension.sales_team_id=MY_TEAM" -d "0.sales_team_dimension.sales_team_name=My Sales Team" \
-d "1.sales_rep_dimension.sales_rep_id=MY_SALESREP" -d "1.sales_rep_dimension.sales_team_id=MY_TEAM" \
<nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

Example with bad authentication:

curl -i -d userlogin=admin -d password=opentapse -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

HTTP/1.1 401 Unauthorized
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Authentication failed.
</body>
</html>

Example of Error when trying to add data in an in-existing field:

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_description=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

HTTP/1.1 500 Internal Server Error
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Data Load error: Error processing the SQL Query
Caused by: Unknown column 'CHANNEL_DESCRIPTION' in 'field list'
</body>
</html>

=== Data Model Reference ===

The following tables and fields can be given:

==== CHANNEL_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CHANNEL_ID || String (60) || The Channel identifier
|-
| CHANNEL_NAME || String (100) || The Channel name
|}

==== SALES_TEAM_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_TEAM_ID || String (60) || The Sales team identifier
|-
| SALES_TEAM_NAME || String (100) || The Sales team name
|}

==== SALES_REP_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_REP_ID || String (60) || The Sales representative identifier
|-
| SALES_TEAM_ID || String (60) || The Sales team identifier, references SALES_TEAM_DIMENSION
|-
| SALES_TEAM_NAME || String (100) || The Sales team name
|-
| FIRST_NAME || String (100) || The Sales representative first name
|-
| LAST_NAME || String (100) || The Sales representative last name
|}

==== CUSTOMER_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CUSTOMER_ID || String (60) || The Customer identifier
|-
| CUSTOMER_NAME || String (255) || The Customer name
|-
| COMPANY_NAME || String (255) || The Customer company name
|-
| INDUSTRY || String (60) || The Customer industry
|-
| FIRST_NAME || String (100) || The Customer first name
|-
| LAST_NAME || String (100) || The Customer last name
|-
| ATTN_NAME || String (100) || The address attention name
|-
| STREET_ADDRESS_LINE1 || String (255) || The address street
|-
| CITY || String (60) || The address city
|-
| STATE || String (60) || The address state
|-
| REGION || String (60) || The address region
|-
| COUNTRY || String (100) || The address country
|-
| POSTAL_CODE3DIGIT || String (3) || The address first 3 digits of the postal code
|-
| POSTAL_CODE || String (60) || The address postal code
|-
| PHONE_COUNTRY || String (60) || The phone number country code
|-
| PHONE_AREA_CODE || String (60) || The phone number area code
|-
| PHONE_NUMBER || String (60) || The rest of the phone number
|-
| PRIMARY_EMAIL || String (255) || The Customer primary email address
|-
| OTHER_EMAIL || String (255) || The Customer other email address
|-
| CUSTOMER_TYPE || String (60) || The Customer type
|-
| SOURCE || String (60) || The source of the Customer
|-
| SALES_TEAM_NAME || String (255) || The name of Sales Team associated to the Customer
|-
| CREATED_DATE_AND_TIME || Timestamp || The time and date, format is ''YYYY-MM-DD hh:mm:ss''
|}

==== PRODUCT_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| PRODUCT_ID || String (60) || The Product identifier
|-
| SKU || String (60) || The Product SKU code
|-
| UPC || String (60) || The Product UPC code
|-
| PRODUCT_NAME || String (100) || The Product name
|-
| BRAND || String (100) || The Product brand
|-
| CATEGORY || String (100) || The Product category name
|-
| SIZE || String (100) || The Product size
|-
| STYLE || String (100) || The Product style
|-
| COLOR || String (100) || The Product color
|-
| WIDTH || Numeric (18,6) || The Product width
|-
| LENGTH || Numeric (18,6) || The Product length
|-
| HEIGHT || Numeric (18,6) || The Product height
|-
| WEIGHT || Numeric (18,6) || The Product weight
|-
| DIAMETER || Numeric (18,6) || The Product diameter
|-
| PRODUCT_TYPE || String (100) || The Product type
|-
| SUPPLIER_NAME || String (100) || The Product supplier name
|-
| ORG_SUPPLIER_ID || String (60) || The Product supplier organization identifier
|-
| EST_BASE_CURRENCY_COST || Numeric (18,6) || The Product estimated cost
|}

==== ORDER_ITEM_FACT ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| ORDER_ID || String (60) || The order identifier
|-
| ORDER_ITEM_SEQ_ID || String (100) || The order item identifier
|-
| CUSTOMER_ID || String (60) || The customer identifier, references the CUSTOMER_DIMENSION
|-
| CHANNEL_ID || String (60) || The channel identifier, references the CHANNEL_DIMENSION
|-
| SALES_REP_ID || String (60)|| The sales representative identifier, references the SALES_REP_DIMENSION
|-
| SALES_REP_TEAM_ID || String (60) || The sales team identifier, references the SALES_TEAM_DIMENSION
|-
| ORDER_DATE || String (Date) || The date the order was placed, format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) || The product identifier, references the PRODUCT_DIMENSION
|-
| QUANTITY || Numeric (18,6) || The quantity of item ordered
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2)||
|-
| RESOLUTION_STATUS || String (25) ||
|-
| RETURNED_QUANTITY || Numeric (18,6) || The quantity of the item that was returned
|-
| RETURNED_GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RETURNED_DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RETURNED_NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|}

==== RETURN_ITEM_FACT ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| RETURN_ID || String (60) || The return identifier
|-
| RETURN_ITEM_SEQ_ID || String (100) || The return item identifier
|-
| CUSTOMER_ID || String (60) || The customer identifier, references the CUSTOMER_DIMENSION
|-
| CHANNEL_ID || String (60) || The channel identifier, references the CHANNEL_DIMENSION
|-
| ORDER_DATE || String (Date) || The date the original order was placed, format is ''YYYY-MM-DD''
|-
| RETURN_DATE || String (Date) || The date the return was performed, format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) || The product identifier, references the PRODUCT_DIMENSION
|-
| QUANTITY || Numeric (18,6) || The quantity of product returned
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RESOLUTION_STATUS || String (25) ||
|}

Opentaps Analytics Data Loader

2011-04-12T14:46:50Z

Jwickers: /* CUSTOMER_DIMENSION */

__TOC__

== Uploaders ==

=== opentaps and OFBiz ===
analytics-upload component help to gather and upload analytical data to server. A few steps should be done to install it with opentaps or OfBiz instance.

# Checkout component into hot-deploy. Use <code>svn co svn://svn.opentaps.org/opentaps/modules/analytics-upload/versions/1.5/trunk analytics-upload</code>
# Adjust settings in config/analytics-uploader.properties. Webkey should be the one for your store in opentaps Analytics.
# Note there are two ''scripts'' value in configuration file, default one to use with opentaps instance and another for OfBiz.
# Start instance and run '''analytics.uploadAnalyticalData''' service.

== API ==

Data Loading is done via an HTTP POST servlet.

The following parameter are required:
* userlogin
* password
* webkey

Then the data to load should be given as one parameter per field using the format ''idx.tablename.fieldname=value'' where ''idx'' is a string used both to order the import (if mutliple record depend on each other via a FK) and discriminate which fields are in the same DB row.

Possible HTTP error codes are:
* 400 Bad Request : missing parameter, invalid field name, bad format, no data to load
* 401 Unauthorized : authentication failed
* 404 Not Found : given webkey does not correspond to an existing Store
* 403 Forbidden : tried to modify a table or field that cannot be modified
* 409 Conflict : found the same rows defined twice
* 500 Internal error : other exception during import

=== Examples ===

The following examples are using the curl command line utility to perform the HTTP POSTs.

Posting data in the ''CHANNEL_DIMENSION'':

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

Returned Success message would be like:

HTTP/1.1 200 OK
...
<html>
<head>
<title>Dataload: success</title>
</head>
<body class="success">
Successfully loaded 1 rows
</body>
</html>

Multiple rows can be inserted in the same request, using the IDX part to order the insertion in case a row needs to reference to a previously loaded row:

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 \
-d "0.sales_team_dimension.sales_team_id=MY_TEAM" -d "0.sales_team_dimension.sales_team_name=My Sales Team" \
-d "1.sales_rep_dimension.sales_rep_id=MY_SALESREP" -d "1.sales_rep_dimension.sales_team_id=MY_TEAM" \
<nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

Example with bad authentication:

curl -i -d userlogin=admin -d password=opentapse -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

HTTP/1.1 401 Unauthorized
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Authentication failed.
</body>
</html>

Example of Error when trying to add data in an in-existing field:

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_description=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

HTTP/1.1 500 Internal Server Error
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Data Load error: Error processing the SQL Query
Caused by: Unknown column 'CHANNEL_DESCRIPTION' in 'field list'
</body>
</html>

=== Data Model Reference ===

The following tables and fields can be given:

==== CHANNEL_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CHANNEL_ID || String (60) || The Channel identifier
|-
| CHANNEL_NAME || String (100) || The Channel name
|}

==== SALES_TEAM_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_TEAM_ID || String (60) || The Sales team identifier
|-
| SALES_TEAM_NAME || String (100) || The Sales team name
|}

==== SALES_REP_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_REP_ID || String (60) || The Sales representative identifier
|-
| SALES_TEAM_ID || String (60) || The Sales team identifier, references SALES_TEAM_DIMENSION
|-
| SALES_TEAM_NAME || String (100) || The Sales team name
|-
| FIRST_NAME || String (100) || The Sales representative first name
|-
| LAST_NAME || String (100) || The Sales representative last name
|}

==== CUSTOMER_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CUSTOMER_ID || String (60) || The Customer identifier
|-
| CUSTOMER_NAME || String (255) || The Customer name
|-
| COMPANY_NAME || String (255) || The Customer company name
|-
| INDUSTRY || String (60) || The Customer industry
|-
| FIRST_NAME || String (100) || The Customer first name
|-
| LAST_NAME || String (100) || The Customer last name
|-
| ATTN_NAME || String (100) || The address attention name
|-
| STREET_ADDRESS_LINE1 || String (255) || The address street
|-
| CITY || String (60) || The address city
|-
| STATE || String (60) || The address state
|-
| REGION || String (60) || The address region
|-
| COUNTRY || String (100) || The address country
|-
| POSTAL_CODE3DIGIT || String (3) || The address first 3 digits of the postal code
|-
| POSTAL_CODE || String (60) || The address postal code
|-
| PHONE_COUNTRY || String (60) || The phone number country code
|-
| PHONE_AREA_CODE || String (60) || The phone number area code
|-
| PHONE_NUMBER || String (60) || The rest of the phone number
|-
| PRIMARY_EMAIL || String (255) || The Customer primary email address
|-
| OTHER_EMAIL || String (255) || The Customer other email address
|-
| CUSTOMER_TYPE || String (60) || The Customer type
|-
| SOURCE || String (60) || The source of the Customer
|-
| SALES_TEAM_NAME || String (255) || The name of Sales Team associated to the Customer
|-
| CREATED_DATE_AND_TIME || Timestamp || The time and date, format os ''YYYY-MM-DD hh:mm:ss''
|}

==== PRODUCT_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| PRODUCT_ID || String (60) || The Product identifier
|-
| SKU || String (60) || The Product SKU code
|-
| UPC || String (60) || The Product UPC code
|-
| PRODUCT_NAME || String (100) || The Product name
|-
| BRAND || String (100) || The Product brand
|-
| CATEGORY || String (100) || The Product category name
|-
| SIZE || String (100) || The Product size
|-
| STYLE || String (100) || The Product style
|-
| COLOR || String (100) || The Product color
|-
| WIDTH || Numeric (18,6) || The Product width
|-
| LENGTH || Numeric (18,6) || The Product length
|-
| HEIGHT || Numeric (18,6) || The Product height
|-
| WEIGHT || Numeric (18,6) || The Product weight
|-
| DIAMETER || Numeric (18,6) || The Product diameter
|-
| PRODUCT_TYPE || String (100) || The Product type
|-
| SUPPLIER_NAME || String (100) || The Product supplier name
|-
| ORG_SUPPLIER_ID || String (60) || The Product supplier organization identifier
|-
| EST_BASE_CURRENCY_COST || Numeric (18,6) || The Product estimated cost
|}

==== ORDER_ITEM_FACT ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| ORDER_ID || String (60) || The order identifier
|-
| ORDER_ITEM_SEQ_ID || String (100) || The order item identifier
|-
| CUSTOMER_ID || String (60) || The customer identifier, references the CUSTOMER_DIMENSION
|-
| CHANNEL_ID || String (60) || The channel identifier, references the CHANNEL_DIMENSION
|-
| SALES_REP_ID || String (60)|| The sales representative identifier, references the SALES_REP_DIMENSION
|-
| SALES_REP_TEAM_ID || String (60) || The sales team identifier, references the SALES_TEAM_DIMENSION
|-
| ORDER_DATE || String (Date) || The date the order was placed, format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) || The product identifier, references the PRODUCT_DIMENSION
|-
| QUANTITY || Numeric (18,6) || The quantity of item ordered
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2)||
|-
| RESOLUTION_STATUS || String (25) ||
|-
| RETURNED_QUANTITY || Numeric (18,6) || The quantity of the item that was returned
|-
| RETURNED_GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RETURNED_DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RETURNED_NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|}

==== RETURN_ITEM_FACT ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| RETURN_ID || String (60) || The return identifier
|-
| RETURN_ITEM_SEQ_ID || String (100) || The return item identifier
|-
| CUSTOMER_ID || String (60) || The customer identifier, references the CUSTOMER_DIMENSION
|-
| CHANNEL_ID || String (60) || The channel identifier, references the CHANNEL_DIMENSION
|-
| ORDER_DATE || String (Date) || The date the original order was placed, format is ''YYYY-MM-DD''
|-
| RETURN_DATE || String (Date) || The date the return was performed, format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) || The product identifier, references the PRODUCT_DIMENSION
|-
| QUANTITY || Numeric (18,6) || The quantity of product returned
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RESOLUTION_STATUS || String (25) ||
|}

Opentaps Analytics Data Loader

2011-04-12T14:46:21Z

Jwickers: /* RETURN_ITEM_FACT */

__TOC__

== Uploaders ==

=== opentaps and OFBiz ===
analytics-upload component help to gather and upload analytical data to server. A few steps should be done to install it with opentaps or OfBiz instance.

# Checkout component into hot-deploy. Use <code>svn co svn://svn.opentaps.org/opentaps/modules/analytics-upload/versions/1.5/trunk analytics-upload</code>
# Adjust settings in config/analytics-uploader.properties. Webkey should be the one for your store in opentaps Analytics.
# Note there are two ''scripts'' value in configuration file, default one to use with opentaps instance and another for OfBiz.
# Start instance and run '''analytics.uploadAnalyticalData''' service.

== API ==

Data Loading is done via an HTTP POST servlet.

The following parameter are required:
* userlogin
* password
* webkey

Then the data to load should be given as one parameter per field using the format ''idx.tablename.fieldname=value'' where ''idx'' is a string used both to order the import (if mutliple record depend on each other via a FK) and discriminate which fields are in the same DB row.

Possible HTTP error codes are:
* 400 Bad Request : missing parameter, invalid field name, bad format, no data to load
* 401 Unauthorized : authentication failed
* 404 Not Found : given webkey does not correspond to an existing Store
* 403 Forbidden : tried to modify a table or field that cannot be modified
* 409 Conflict : found the same rows defined twice
* 500 Internal error : other exception during import

=== Examples ===

The following examples are using the curl command line utility to perform the HTTP POSTs.

Posting data in the ''CHANNEL_DIMENSION'':

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

Returned Success message would be like:

HTTP/1.1 200 OK
...
<html>
<head>
<title>Dataload: success</title>
</head>
<body class="success">
Successfully loaded 1 rows
</body>
</html>

Multiple rows can be inserted in the same request, using the IDX part to order the insertion in case a row needs to reference to a previously loaded row:

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 \
-d "0.sales_team_dimension.sales_team_id=MY_TEAM" -d "0.sales_team_dimension.sales_team_name=My Sales Team" \
-d "1.sales_rep_dimension.sales_rep_id=MY_SALESREP" -d "1.sales_rep_dimension.sales_team_id=MY_TEAM" \
<nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

Example with bad authentication:

curl -i -d userlogin=admin -d password=opentapse -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

HTTP/1.1 401 Unauthorized
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Authentication failed.
</body>
</html>

Example of Error when trying to add data in an in-existing field:

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_description=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

HTTP/1.1 500 Internal Server Error
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Data Load error: Error processing the SQL Query
Caused by: Unknown column 'CHANNEL_DESCRIPTION' in 'field list'
</body>
</html>

=== Data Model Reference ===

The following tables and fields can be given:

==== CHANNEL_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CHANNEL_ID || String (60) || The Channel identifier
|-
| CHANNEL_NAME || String (100) || The Channel name
|}

==== SALES_TEAM_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_TEAM_ID || String (60) || The Sales team identifier
|-
| SALES_TEAM_NAME || String (100) || The Sales team name
|}

==== SALES_REP_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_REP_ID || String (60) || The Sales representative identifier
|-
| SALES_TEAM_ID || String (60) || The Sales team identifier, references SALES_TEAM_DIMENSION
|-
| SALES_TEAM_NAME || String (100) || The Sales team name
|-
| FIRST_NAME || String (100) || The Sales representative first name
|-
| LAST_NAME || String (100) || The Sales representative last name
|}

==== CUSTOMER_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CUSTOMER_ID || String (60) || The Customer identifier
|-
| CUSTOMER_NAME || String (255) || The Customer name
|-
| COMPANY_NAME || String (255) || The Customer company name
|-
| INDUSTRY || String (60) || The Customer industry
|-
| FIRST_NAME || String (100) || The Customer first name
|-
| LAST_NAME || String (100) || The Customer last name
|-
| ATTN_NAME || String (100) || The address attention name
|-
| STREET_ADDRESS_LINE1 || String (255) || The address street
|-
| CITY || String (60) || The address city
|-
| STATE || String (60) || The address state
|-
| REGION || String (60) || The address region
|-
| COUNTRY || String (100) || The address country
|-
| POSTAL_CODE3DIGIT || String (3) || The address first 3 digits of the postal code
|-
| POSTAL_CODE || String (60) || The address postal code
|-
| PHONE_COUNTRY || String (60) || The phone number country code
|-
| PHONE_AREA_CODE || String (60) || The phone number area code
|-
| PHONE_NUMBER || String (60) || The rest of the phone number
|-
| PRIMARY_EMAIL || String (255) || The Customer primary email address
|-
| OTHER_EMAIL || String (255) || The Customer other email address
|-
| CUSTOMER_TYPE || String (60) || The Customer type
|-
| SOURCE || String (60) || The source of the Customer
|-
| SALES_TEAM_NAME || String (255) || The name of Sales Team associated to the Customer
|-
| CREATED_DATE_AND_TIME || Timestamp || The time and date, given as "YYYY-MM-DD hh:mm:ss"
|}

==== PRODUCT_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| PRODUCT_ID || String (60) || The Product identifier
|-
| SKU || String (60) || The Product SKU code
|-
| UPC || String (60) || The Product UPC code
|-
| PRODUCT_NAME || String (100) || The Product name
|-
| BRAND || String (100) || The Product brand
|-
| CATEGORY || String (100) || The Product category name
|-
| SIZE || String (100) || The Product size
|-
| STYLE || String (100) || The Product style
|-
| COLOR || String (100) || The Product color
|-
| WIDTH || Numeric (18,6) || The Product width
|-
| LENGTH || Numeric (18,6) || The Product length
|-
| HEIGHT || Numeric (18,6) || The Product height
|-
| WEIGHT || Numeric (18,6) || The Product weight
|-
| DIAMETER || Numeric (18,6) || The Product diameter
|-
| PRODUCT_TYPE || String (100) || The Product type
|-
| SUPPLIER_NAME || String (100) || The Product supplier name
|-
| ORG_SUPPLIER_ID || String (60) || The Product supplier organization identifier
|-
| EST_BASE_CURRENCY_COST || Numeric (18,6) || The Product estimated cost
|}

==== ORDER_ITEM_FACT ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| ORDER_ID || String (60) || The order identifier
|-
| ORDER_ITEM_SEQ_ID || String (100) || The order item identifier
|-
| CUSTOMER_ID || String (60) || The customer identifier, references the CUSTOMER_DIMENSION
|-
| CHANNEL_ID || String (60) || The channel identifier, references the CHANNEL_DIMENSION
|-
| SALES_REP_ID || String (60)|| The sales representative identifier, references the SALES_REP_DIMENSION
|-
| SALES_REP_TEAM_ID || String (60) || The sales team identifier, references the SALES_TEAM_DIMENSION
|-
| ORDER_DATE || String (Date) || The date the order was placed, format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) || The product identifier, references the PRODUCT_DIMENSION
|-
| QUANTITY || Numeric (18,6) || The quantity of item ordered
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2)||
|-
| RESOLUTION_STATUS || String (25) ||
|-
| RETURNED_QUANTITY || Numeric (18,6) || The quantity of the item that was returned
|-
| RETURNED_GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RETURNED_DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RETURNED_NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|}

==== RETURN_ITEM_FACT ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| RETURN_ID || String (60) || The return identifier
|-
| RETURN_ITEM_SEQ_ID || String (100) || The return item identifier
|-
| CUSTOMER_ID || String (60) || The customer identifier, references the CUSTOMER_DIMENSION
|-
| CHANNEL_ID || String (60) || The channel identifier, references the CHANNEL_DIMENSION
|-
| ORDER_DATE || String (Date) || The date the original order was placed, format is ''YYYY-MM-DD''
|-
| RETURN_DATE || String (Date) || The date the return was performed, format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) || The product identifier, references the PRODUCT_DIMENSION
|-
| QUANTITY || Numeric (18,6) || The quantity of product returned
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RESOLUTION_STATUS || String (25) ||
|}

Opentaps Analytics Data Loader

2011-04-12T14:44:57Z

Jwickers: /* ORDER_ITEM_FACT */

__TOC__

== Uploaders ==

=== opentaps and OFBiz ===
analytics-upload component help to gather and upload analytical data to server. A few steps should be done to install it with opentaps or OfBiz instance.

# Checkout component into hot-deploy. Use <code>svn co svn://svn.opentaps.org/opentaps/modules/analytics-upload/versions/1.5/trunk analytics-upload</code>
# Adjust settings in config/analytics-uploader.properties. Webkey should be the one for your store in opentaps Analytics.
# Note there are two ''scripts'' value in configuration file, default one to use with opentaps instance and another for OfBiz.
# Start instance and run '''analytics.uploadAnalyticalData''' service.

== API ==

Data Loading is done via an HTTP POST servlet.

The following parameter are required:
* userlogin
* password
* webkey

Then the data to load should be given as one parameter per field using the format ''idx.tablename.fieldname=value'' where ''idx'' is a string used both to order the import (if mutliple record depend on each other via a FK) and discriminate which fields are in the same DB row.

Possible HTTP error codes are:
* 400 Bad Request : missing parameter, invalid field name, bad format, no data to load
* 401 Unauthorized : authentication failed
* 404 Not Found : given webkey does not correspond to an existing Store
* 403 Forbidden : tried to modify a table or field that cannot be modified
* 409 Conflict : found the same rows defined twice
* 500 Internal error : other exception during import

=== Examples ===

The following examples are using the curl command line utility to perform the HTTP POSTs.

Posting data in the ''CHANNEL_DIMENSION'':

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

Returned Success message would be like:

HTTP/1.1 200 OK
...
<html>
<head>
<title>Dataload: success</title>
</head>
<body class="success">
Successfully loaded 1 rows
</body>
</html>

Multiple rows can be inserted in the same request, using the IDX part to order the insertion in case a row needs to reference to a previously loaded row:

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 \
-d "0.sales_team_dimension.sales_team_id=MY_TEAM" -d "0.sales_team_dimension.sales_team_name=My Sales Team" \
-d "1.sales_rep_dimension.sales_rep_id=MY_SALESREP" -d "1.sales_rep_dimension.sales_team_id=MY_TEAM" \
<nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

Example with bad authentication:

curl -i -d userlogin=admin -d password=opentapse -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

HTTP/1.1 401 Unauthorized
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Authentication failed.
</body>
</html>

Example of Error when trying to add data in an in-existing field:

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_description=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

HTTP/1.1 500 Internal Server Error
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Data Load error: Error processing the SQL Query
Caused by: Unknown column 'CHANNEL_DESCRIPTION' in 'field list'
</body>
</html>

=== Data Model Reference ===

The following tables and fields can be given:

==== CHANNEL_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CHANNEL_ID || String (60) || The Channel identifier
|-
| CHANNEL_NAME || String (100) || The Channel name
|}

==== SALES_TEAM_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_TEAM_ID || String (60) || The Sales team identifier
|-
| SALES_TEAM_NAME || String (100) || The Sales team name
|}

==== SALES_REP_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_REP_ID || String (60) || The Sales representative identifier
|-
| SALES_TEAM_ID || String (60) || The Sales team identifier, references SALES_TEAM_DIMENSION
|-
| SALES_TEAM_NAME || String (100) || The Sales team name
|-
| FIRST_NAME || String (100) || The Sales representative first name
|-
| LAST_NAME || String (100) || The Sales representative last name
|}

==== CUSTOMER_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CUSTOMER_ID || String (60) || The Customer identifier
|-
| CUSTOMER_NAME || String (255) || The Customer name
|-
| COMPANY_NAME || String (255) || The Customer company name
|-
| INDUSTRY || String (60) || The Customer industry
|-
| FIRST_NAME || String (100) || The Customer first name
|-
| LAST_NAME || String (100) || The Customer last name
|-
| ATTN_NAME || String (100) || The address attention name
|-
| STREET_ADDRESS_LINE1 || String (255) || The address street
|-
| CITY || String (60) || The address city
|-
| STATE || String (60) || The address state
|-
| REGION || String (60) || The address region
|-
| COUNTRY || String (100) || The address country
|-
| POSTAL_CODE3DIGIT || String (3) || The address first 3 digits of the postal code
|-
| POSTAL_CODE || String (60) || The address postal code
|-
| PHONE_COUNTRY || String (60) || The phone number country code
|-
| PHONE_AREA_CODE || String (60) || The phone number area code
|-
| PHONE_NUMBER || String (60) || The rest of the phone number
|-
| PRIMARY_EMAIL || String (255) || The Customer primary email address
|-
| OTHER_EMAIL || String (255) || The Customer other email address
|-
| CUSTOMER_TYPE || String (60) || The Customer type
|-
| SOURCE || String (60) || The source of the Customer
|-
| SALES_TEAM_NAME || String (255) || The name of Sales Team associated to the Customer
|-
| CREATED_DATE_AND_TIME || Timestamp || The time and date, given as "YYYY-MM-DD hh:mm:ss"
|}

==== PRODUCT_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| PRODUCT_ID || String (60) || The Product identifier
|-
| SKU || String (60) || The Product SKU code
|-
| UPC || String (60) || The Product UPC code
|-
| PRODUCT_NAME || String (100) || The Product name
|-
| BRAND || String (100) || The Product brand
|-
| CATEGORY || String (100) || The Product category name
|-
| SIZE || String (100) || The Product size
|-
| STYLE || String (100) || The Product style
|-
| COLOR || String (100) || The Product color
|-
| WIDTH || Numeric (18,6) || The Product width
|-
| LENGTH || Numeric (18,6) || The Product length
|-
| HEIGHT || Numeric (18,6) || The Product height
|-
| WEIGHT || Numeric (18,6) || The Product weight
|-
| DIAMETER || Numeric (18,6) || The Product diameter
|-
| PRODUCT_TYPE || String (100) || The Product type
|-
| SUPPLIER_NAME || String (100) || The Product supplier name
|-
| ORG_SUPPLIER_ID || String (60) || The Product supplier organization identifier
|-
| EST_BASE_CURRENCY_COST || Numeric (18,6) || The Product estimated cost
|}

==== ORDER_ITEM_FACT ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| ORDER_ID || String (60) || The order identifier
|-
| ORDER_ITEM_SEQ_ID || String (100) || The order item identifier
|-
| CUSTOMER_ID || String (60) || The customer identifier, references the CUSTOMER_DIMENSION
|-
| CHANNEL_ID || String (60) || The channel identifier, references the CHANNEL_DIMENSION
|-
| SALES_REP_ID || String (60)|| The sales representative identifier, references the SALES_REP_DIMENSION
|-
| SALES_REP_TEAM_ID || String (60) || The sales team identifier, references the SALES_TEAM_DIMENSION
|-
| ORDER_DATE || String (Date) || The date the order was placed, format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) || The product identifier, references the PRODUCT_DIMENSION
|-
| QUANTITY || Numeric (18,6) || The quantity of item ordered
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2)||
|-
| RESOLUTION_STATUS || String (25) ||
|-
| RETURNED_QUANTITY || Numeric (18,6) || The quantity of the item that was returned
|-
| RETURNED_GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RETURNED_DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RETURNED_NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|}

==== RETURN_ITEM_FACT ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| RETURN_ID || String (60) ||
|-
| RETURN_ITEM_SEQ_ID || String (100) ||
|-
| CUSTOMER_ID || String (60) ||
|-
| CHANNEL_ID || String (60) ||
|-
| ORDER_DATE || String (Date) || Format is ''YYYY-MM-DD''
|-
| RETURN_DATE || String (Date) || Format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) ||
|-
| QUANTITY || Numeric (18,6) ||
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RESOLUTION_STATUS || String (25) ||
|}

Opentaps Analytics Data Loader

2011-04-12T14:42:33Z

Jwickers: /* PRODUCT_DIMENSION */

__TOC__

== Uploaders ==

=== opentaps and OFBiz ===
analytics-upload component help to gather and upload analytical data to server. A few steps should be done to install it with opentaps or OfBiz instance.

# Checkout component into hot-deploy. Use <code>svn co svn://svn.opentaps.org/opentaps/modules/analytics-upload/versions/1.5/trunk analytics-upload</code>
# Adjust settings in config/analytics-uploader.properties. Webkey should be the one for your store in opentaps Analytics.
# Note there are two ''scripts'' value in configuration file, default one to use with opentaps instance and another for OfBiz.
# Start instance and run '''analytics.uploadAnalyticalData''' service.

== API ==

Data Loading is done via an HTTP POST servlet.

The following parameter are required:
* userlogin
* password
* webkey

Then the data to load should be given as one parameter per field using the format ''idx.tablename.fieldname=value'' where ''idx'' is a string used both to order the import (if mutliple record depend on each other via a FK) and discriminate which fields are in the same DB row.

Possible HTTP error codes are:
* 400 Bad Request : missing parameter, invalid field name, bad format, no data to load
* 401 Unauthorized : authentication failed
* 404 Not Found : given webkey does not correspond to an existing Store
* 403 Forbidden : tried to modify a table or field that cannot be modified
* 409 Conflict : found the same rows defined twice
* 500 Internal error : other exception during import

=== Examples ===

The following examples are using the curl command line utility to perform the HTTP POSTs.

Posting data in the ''CHANNEL_DIMENSION'':

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

Returned Success message would be like:

HTTP/1.1 200 OK
...
<html>
<head>
<title>Dataload: success</title>
</head>
<body class="success">
Successfully loaded 1 rows
</body>
</html>

Multiple rows can be inserted in the same request, using the IDX part to order the insertion in case a row needs to reference to a previously loaded row:

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 \
-d "0.sales_team_dimension.sales_team_id=MY_TEAM" -d "0.sales_team_dimension.sales_team_name=My Sales Team" \
-d "1.sales_rep_dimension.sales_rep_id=MY_SALESREP" -d "1.sales_rep_dimension.sales_team_id=MY_TEAM" \
<nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

Example with bad authentication:

curl -i -d userlogin=admin -d password=opentapse -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

HTTP/1.1 401 Unauthorized
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Authentication failed.
</body>
</html>

Example of Error when trying to add data in an in-existing field:

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_description=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

HTTP/1.1 500 Internal Server Error
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Data Load error: Error processing the SQL Query
Caused by: Unknown column 'CHANNEL_DESCRIPTION' in 'field list'
</body>
</html>

=== Data Model Reference ===

The following tables and fields can be given:

==== CHANNEL_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CHANNEL_ID || String (60) || The Channel identifier
|-
| CHANNEL_NAME || String (100) || The Channel name
|}

==== SALES_TEAM_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_TEAM_ID || String (60) || The Sales team identifier
|-
| SALES_TEAM_NAME || String (100) || The Sales team name
|}

==== SALES_REP_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_REP_ID || String (60) || The Sales representative identifier
|-
| SALES_TEAM_ID || String (60) || The Sales team identifier, references SALES_TEAM_DIMENSION
|-
| SALES_TEAM_NAME || String (100) || The Sales team name
|-
| FIRST_NAME || String (100) || The Sales representative first name
|-
| LAST_NAME || String (100) || The Sales representative last name
|}

==== CUSTOMER_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CUSTOMER_ID || String (60) || The Customer identifier
|-
| CUSTOMER_NAME || String (255) || The Customer name
|-
| COMPANY_NAME || String (255) || The Customer company name
|-
| INDUSTRY || String (60) || The Customer industry
|-
| FIRST_NAME || String (100) || The Customer first name
|-
| LAST_NAME || String (100) || The Customer last name
|-
| ATTN_NAME || String (100) || The address attention name
|-
| STREET_ADDRESS_LINE1 || String (255) || The address street
|-
| CITY || String (60) || The address city
|-
| STATE || String (60) || The address state
|-
| REGION || String (60) || The address region
|-
| COUNTRY || String (100) || The address country
|-
| POSTAL_CODE3DIGIT || String (3) || The address first 3 digits of the postal code
|-
| POSTAL_CODE || String (60) || The address postal code
|-
| PHONE_COUNTRY || String (60) || The phone number country code
|-
| PHONE_AREA_CODE || String (60) || The phone number area code
|-
| PHONE_NUMBER || String (60) || The rest of the phone number
|-
| PRIMARY_EMAIL || String (255) || The Customer primary email address
|-
| OTHER_EMAIL || String (255) || The Customer other email address
|-
| CUSTOMER_TYPE || String (60) || The Customer type
|-
| SOURCE || String (60) || The source of the Customer
|-
| SALES_TEAM_NAME || String (255) || The name of Sales Team associated to the Customer
|-
| CREATED_DATE_AND_TIME || Timestamp || The time and date, given as "YYYY-MM-DD hh:mm:ss"
|}

==== PRODUCT_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| PRODUCT_ID || String (60) || The Product identifier
|-
| SKU || String (60) || The Product SKU code
|-
| UPC || String (60) || The Product UPC code
|-
| PRODUCT_NAME || String (100) || The Product name
|-
| BRAND || String (100) || The Product brand
|-
| CATEGORY || String (100) || The Product category name
|-
| SIZE || String (100) || The Product size
|-
| STYLE || String (100) || The Product style
|-
| COLOR || String (100) || The Product color
|-
| WIDTH || Numeric (18,6) || The Product width
|-
| LENGTH || Numeric (18,6) || The Product length
|-
| HEIGHT || Numeric (18,6) || The Product height
|-
| WEIGHT || Numeric (18,6) || The Product weight
|-
| DIAMETER || Numeric (18,6) || The Product diameter
|-
| PRODUCT_TYPE || String (100) || The Product type
|-
| SUPPLIER_NAME || String (100) || The Product supplier name
|-
| ORG_SUPPLIER_ID || String (60) || The Product supplier organization identifier
|-
| EST_BASE_CURRENCY_COST || Numeric (18,6) || The Product estimated cost
|}

==== ORDER_ITEM_FACT ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| ORDER_ID || String (60) ||
|-
| ORDER_ITEM_SEQ_ID || String (100) ||
|-
| CUSTOMER_ID || String (60) ||
|-
| CHANNEL_ID || String (60) ||
|-
| SALES_REP_ID || String (60)||
|-
| SALES_REP_TEAM_ID || String (60) ||
|-
| ORDER_DATE || String (Date) || Format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) ||
|-
| QUANTITY || Numeric (18,6) ||
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2)||
|-
| RESOLUTION_STATUS || String (25) ||
|-
| RETURNED_QUANTITY || Numeric (18,6) ||
|-
| RETURNED_GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RETURNED_DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RETURNED_NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|}

==== RETURN_ITEM_FACT ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| RETURN_ID || String (60) ||
|-
| RETURN_ITEM_SEQ_ID || String (100) ||
|-
| CUSTOMER_ID || String (60) ||
|-
| CHANNEL_ID || String (60) ||
|-
| ORDER_DATE || String (Date) || Format is ''YYYY-MM-DD''
|-
| RETURN_DATE || String (Date) || Format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) ||
|-
| QUANTITY || Numeric (18,6) ||
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RESOLUTION_STATUS || String (25) ||
|}

Opentaps Analytics Data Loader

2011-04-12T13:17:22Z

Jwickers: /* CHANNEL_DIMENSION */

__TOC__

== Uploaders ==

=== opentaps and OFBiz ===
analytics-upload component help to gather and upload analytical data to server. A few steps should be done to install it with opentaps or OfBiz instance.

# Checkout component into hot-deploy. Use <code>svn co svn://svn.opentaps.org/opentaps/modules/analytics-upload/versions/1.5/trunk analytics-upload</code>
# Adjust settings in config/analytics-uploader.properties. Webkey should be the one for your store in opentaps Analytics.
# Note there are two ''scripts'' value in configuration file, default one to use with opentaps instance and another for OfBiz.
# Start instance and run '''analytics.uploadAnalyticalData''' service.

== API ==

Data Loading is done via an HTTP POST servlet.

The following parameter are required:
* userlogin
* password
* webkey

Then the data to load should be given as one parameter per field using the format ''idx.tablename.fieldname=value'' where ''idx'' is a string used both to order the import (if mutliple record depend on each other via a FK) and discriminate which fields are in the same DB row.

Possible HTTP error codes are:
* 400 Bad Request : missing parameter, invalid field name, bad format, no data to load
* 401 Unauthorized : authentication failed
* 404 Not Found : given webkey does not correspond to an existing Store
* 403 Forbidden : tried to modify a table or field that cannot be modified
* 409 Conflict : found the same rows defined twice
* 500 Internal error : other exception during import

=== Examples ===

The following examples are using the curl command line utility to perform the HTTP POSTs.

Posting data in the ''CHANNEL_DIMENSION'':

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

Returned Success message would be like:

HTTP/1.1 200 OK
...
<html>
<head>
<title>Dataload: success</title>
</head>
<body class="success">
Successfully loaded 1 rows
</body>
</html>

Multiple rows can be inserted in the same request, using the IDX part to order the insertion in case a row needs to reference to a previously loaded row:

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 \
-d "0.sales_team_dimension.sales_team_id=MY_TEAM" -d "0.sales_team_dimension.sales_team_name=My Sales Team" \
-d "1.sales_rep_dimension.sales_rep_id=MY_SALESREP" -d "1.sales_rep_dimension.sales_team_id=MY_TEAM" \
<nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

Example with bad authentication:

curl -i -d userlogin=admin -d password=opentapse -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_name=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

HTTP/1.1 401 Unauthorized
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Authentication failed.
</body>
</html>

Example of Error when trying to add data in an in-existing field:

curl -i -d userlogin=admin -d password=opentaps -d webkey=thisisatest1234 -d "0.channel_dimension.channel_id=MY_CHANNEL" -d "0.channel_dimension.channel_description=My Channel" <nowiki>http://127.0.0.1:8080/analytics/control/loaddata</nowiki>

HTTP/1.1 500 Internal Server Error
...
<html>
<head>
<title>Dataload: error</title>
</head>
<body class="error">
Data Load error: Error processing the SQL Query
Caused by: Unknown column 'CHANNEL_DESCRIPTION' in 'field list'
</body>
</html>

=== Data Model Reference ===

The following tables and fields can be given:

==== CHANNEL_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CHANNEL_ID || String (60) || The Channel identifier
|-
| CHANNEL_NAME || String (100) || The Channel name
|}

==== SALES_TEAM_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_TEAM_ID || String (60) || The Sales team identifier
|-
| SALES_TEAM_NAME || String (100) || The Sales team name
|}

==== SALES_REP_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| SALES_REP_ID || String (60) || The Sales representative identifier
|-
| SALES_TEAM_ID || String (60) || The Sales team identifier, references SALES_TEAM_DIMENSION
|-
| SALES_TEAM_NAME || String (100) || The Sales team name
|-
| FIRST_NAME || String (100) || The Sales representative first name
|-
| LAST_NAME || String (100) || The Sales representative last name
|}

==== CUSTOMER_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| CUSTOMER_ID || String (60) || The Customer identifier
|-
| CUSTOMER_NAME || String (255) || The Customer name
|-
| COMPANY_NAME || String (255) || The Customer company name
|-
| INDUSTRY || String (60) || The Customer industry
|-
| FIRST_NAME || String (100) || The Customer first name
|-
| LAST_NAME || String (100) || The Customer last name
|-
| ATTN_NAME || String (100) || The address attention name
|-
| STREET_ADDRESS_LINE1 || String (255) || The address street
|-
| CITY || String (60) || The address city
|-
| STATE || String (60) || The address state
|-
| REGION || String (60) || The address region
|-
| COUNTRY || String (100) || The address country
|-
| POSTAL_CODE3DIGIT || String (3) || The address first 3 digits of the postal code
|-
| POSTAL_CODE || String (60) || The address postal code
|-
| PHONE_COUNTRY || String (60) || The phone number country code
|-
| PHONE_AREA_CODE || String (60) || The phone number area code
|-
| PHONE_NUMBER || String (60) || The rest of the phone number
|-
| PRIMARY_EMAIL || String (255) || The Customer primary email address
|-
| OTHER_EMAIL || String (255) || The Customer other email address
|-
| CUSTOMER_TYPE || String (60) || The Customer type
|-
| SOURCE || String (60) || The source of the Customer
|-
| SALES_TEAM_NAME || String (255) || The name of Sales Team associated to the Customer
|-
| CREATED_DATE_AND_TIME || Timestamp || The time and date, given as "YYYY-MM-DD hh:mm:ss"
|}

==== PRODUCT_DIMENSION ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| PRODUCT_ID || String (60) || The Product identifier
|-
| SKU || String (60) || The Product SKU code
|-
| UPC || String (60) || The Product UPC code
|-
| PRODUCT_NAME || String (100) || The Product name
|-
| BRAND || String (100) || The Product brand
|-
| CATEGORY || String (100) || The Product category name
|-
| SIZE || String (100) || The Product size
|-
| STYLE || String (100) || The Product style
|-
| COLOR || String (100) || The Product color
|-
| WIDTH || Numeric (18,6) || The Product width
|-
| LENGTH || Numeric (18,6) ||
|-
| HEIGHT || Numeric (18,6) ||
|-
| WEIGHT || Numeric (18,6) ||
|-
| DIAMETER || Numeric (18,6) ||
|-
| PRODUCT_TYPE || String (100) ||
|-
| SUPPLIER_NAME || String (100) ||
|-
| ORG_SUPPLIER_ID || String (60) ||
|-
| EST_BASE_CURRENCY_COST || Numeric (18,6) ||
|}

==== ORDER_ITEM_FACT ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| ORDER_ID || String (60) ||
|-
| ORDER_ITEM_SEQ_ID || String (100) ||
|-
| CUSTOMER_ID || String (60) ||
|-
| CHANNEL_ID || String (60) ||
|-
| SALES_REP_ID || String (60)||
|-
| SALES_REP_TEAM_ID || String (60) ||
|-
| ORDER_DATE || String (Date) || Format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) ||
|-
| QUANTITY || Numeric (18,6) ||
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2)||
|-
| RESOLUTION_STATUS || String (25) ||
|-
| RETURNED_QUANTITY || Numeric (18,6) ||
|-
| RETURNED_GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RETURNED_DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RETURNED_NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|}

==== RETURN_ITEM_FACT ====

{| border="1" cellspacing="0" cellpadding="5"
!width="200"|Field name
!width="200"|Type
!width="500"|Description
|-
| RETURN_ID || String (60) ||
|-
| RETURN_ITEM_SEQ_ID || String (100) ||
|-
| CUSTOMER_ID || String (60) ||
|-
| CHANNEL_ID || String (60) ||
|-
| ORDER_DATE || String (Date) || Format is ''YYYY-MM-DD''
|-
| RETURN_DATE || String (Date) || Format is ''YYYY-MM-DD''
|-
| PRODUCT_ID || String (60) ||
|-
| QUANTITY || Numeric (18,6) ||
|-
| GROSS_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| NET_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| DISCOUNT_AMOUNT_BASE_CURRENCY || Numeric (18,2) ||
|-
| RESOLUTION_STATUS || String (25) ||
|}

Opentaps Analytics Data Loader

2011-04-12T12:25:00Z

Jwickers: /* Data Model Reference */

Opentaps Analytics Data Loader

2011-04-11T16:13:38Z

Jwickers: /* API */

Release Testing

2011-02-21T12:59:11Z

Jwickers: /* Release Testing */

==Release Testing==

These are some general tests, which should be performed prior to releases:

* checkout opentaps from the SVN

* Make sure that ant run-install works.
* Then check the basic functionality for doing the following:
** CRM - create leads, qualify them, convert them to accounts, create notes, opportunities, tasks, events
** Catalog - create new categories and products, make sure they show up on ecommerce
** ecommerce - see new products, sign up as new customer, place orders, see order history
** purchasing -- creating new supplier with contact information
** catalog - create purchasing information for supplier
** purchasing -- create purchase orders for product
** warehouse -- receive products on purchase orders, verify that the inventory in the warehouse has increased.
** warehouse - Pack & ship orders, verify that the inventory has decreased.
** warehouse -- create a production run for PROD_MANUF, schedule and confirm it, make sure that it shows up on the calendar, complete the production run, and make sure that the inventory for PROD_MANUF has increased and the inventory for MAT_A_COST and MAT_B_COST have decreased.
** Order - create sales and purchase orders
** Financials - see invoices and trial balances. Trial balances should always be equal on debit & credit.

* Make sure ant run-tests works

==Release Packaging==

* from a fresh checkout, run ant run-install
* change the release version in framework/common/config/CommonUiLabels.xml
* make sure the GWT configuration is set to compile for all locals and all browser in opentaps-common/src/common/org/opentaps/gwt/common/common.gwt.xml
** uncomment all extend-property
** comment out <set-property name="user.agent" ..>
* don't forget to regenerate the labels after that
* run ant (so the GWT modules are rebuilt)
* remove logs in runtime/logs
* make a zip file with the root directory which should be opentaps-{version} (for example opentaps-1.0.2). Also note that we do include the .svn directories in the release (pointing to the trunk).
* unzip the file and verify that the data has been installed

'''Make sure your package contains the demo data installed in localderby database.'''

Customizing opentaps Applications

2011-02-08T13:50:34Z

Jwickers: /* Webapp User Interface Database Entities */

Frequently you will need to customize opentaps applications, such as change the tabs or shortcuts at the top or add new screens. Beginning with opentaps 1.5, you can make these changes without affecting the core opentaps code, making it easier for you to upgrade later when new versions of opentaps becomes available.

opentaps 1.5 supports the following new features to help you customize its applications:
* The tabs and shortcuts available are now stored in the database, so you can rearrange or change the user interface labels.
* Other user interface elements are also now defined in configuration database entities.
* You can "inject" new controller entries into opentaps applications, making it possible to load your screens and actions into an opentaps application.

__TOC__

==Webapp User Interface Database Entities==

'''OpentapsWebApps''' : defines a webapp (eg: crmsfa, financials), they are listed in the top navigation menu.
* linkUrl should correspond to the home page of the application (eg: /crmsfa/control/main).
* shortName, description, applicationName, imageUrl and imageHoverUrl are used in the opentaps main home page (accessed at /opentaps)
* shortName is also used in top navigation menu as the link label
* sequenceNum is to specify the display order in the nvaigation menu and the opentaps main home page

'''OpentapsWebAppTab''' : a webapp may have multiple tabs (eg: home, orders, accounts .. in crmsfa), they are listed as tabs in the webapp below the top navigation menu.
* uiLabel is the label of the tab, this can use a localized string when present in one of the localized resources, else will be displayed as is
* linkUrl can be just the request name in the application, or if isExternal is set to Y it will be used as is (eg: /opentaps, http://www.example.com/somewhere for external urls)
* sequenceNum is to specify the display order
* securityModule, securityAction, handlerMethod, handlerParameter see below

'''OpentapsShortcutGroup''' : a shortcut group is a small menu in the left column of the page with a title and a list of shortcuts (links), and it belongs to a tab
* uiLabel is the label of the title of the group, this can use a localized string when present in one of the localized resources, else will be displayed as is. If left blank it defaults to the localized string "Shortcuts"
* sequenceNum is to specify the display order
* securityModule, securityAction, handlerMethod, handlerParameter see below

'''OpentapsShortcut''' : a link in a shortcut group
* uiLabel is the label of the shortcut, this can use a localized string when present in one of the localized resources, else will be displayed as is
* linkUrl can be just the request name in the application, or if isExternal is set to Y it will be used as is (eg: /opentaps, http://www.example.com/somewhere for external urls)
* sequenceNum is to specify the display order
* securityModule, securityAction, handlerMethod, handlerParameter see below

===String substitution===

In OpentapsWebAppTab, OpentapsShortcutGroup and OpentapsShortcut the linkUrl and uiLabel supports automatic substitutions according to the current context so "${foo}" will be changed into the context value of "foo".

===Permission===

OpentapsWebAppTab, OpentapsShortcutGroup and OpentapsShortcut all have the securityModule and securityAction fields to specify a basic permission the user must have in order to see the corresponding entity. eg: securityModule="CRMSFA_CONTACTS" securityAction="VIEW" for the contact tab.

Note: this only affects the display on the page, not actual access control (yet).

===Handlers===

In some cases the basic permission will not be enough, or we need more control over what should actually be displayed or not. For this the handlerMethod and handlerParameter fields can be used.

handlerMethod is java method that takes a context Map (Map<String, Object>) and the entity being checked (OpentapsWebAppTab or OpentapsShortcutGroup or OpentapsShortcut or a generic <T extends EntityInterface>) as parameters, and returns the given entity.
This method is called before display and is then free to modify any part of the entity like url, label which will then affect how it is displayed to the current user; and if the entity should not be displayed it can simply return null.
handlerParameter can then be used to provide data to a generic handler (like a complex permission to check, a view preference, etc ...)

Example of handlers:

* ''org.opentaps.warehouse.security.WarehouseSecurity.checkFacilityPermission'' : checks the current user permission on the current facility (as selected when entering the warehouse application) against the permission set in handlerParameter
* ''org.opentaps.webapp.handlers.CommonHandlers.checkSessionValueAbsent'' : checks if the user session does not contain the key specified by handlerParameter (or has a null value)
* ''org.opentaps.webapp.handlers.CommonHandlers.checkSessionValuePresent'' : checks if the user session contains the key specified by handlerParameter (has a non null value)
* ''org.opentaps.webapp.handlers.CommonHandlers.checkHasNoCart'' : check the current user session does not have a shopping cart
* ''org.opentaps.webapp.handlers.CommonHandlers.checkHasCart'' : check the current user session has a shopping cart
* ''org.opentaps.webapp.handlers.CommonHandlers.checkBoolean'' : check the current context has a value named by handlerParameter as a boolean True or a string Y/y
* ''org.opentaps.webapp.handlers.CommonHandlers.checkViewPreferenceForTab'' : check the current user view preference in the current tab; handlerParameter should contain 2 colon separated values: prefType:valueToCheck:default (eg: "MY_OR_TEAM_ACCOUNTS:MY_VALUES:TEAM_VALUES" checks if the MY_OR_TEAM_ACCOUNTS view preference is set to MY_VALUES, and use TEAM_VALUES as default if the view preference is empty)

==Controller Injection==

The '''ControllerInject''' entity allows to inject a controller xml file into another. Usually this is done to customize one of the existing application without modifying their controller file directly, and so keeping the customization isolated from the base code.

The ''injectUrl'' field specify the url of the controller to inject, and ''injectIntoUrl'' the target controller.

For example see the ''opentaps/controllerinjectex'' component, activate it by:
* add ''<load-component component-location="controllerinjectex"/>'' in ''opentaps/component-load.xml''

Then either mount is a normal webapp:
* uncomment the ''webapp'' definition in its ''ofbiz-component.xml''
* access ''/controllerinjectex/'' in a browser

Or use the controller injection by:
* importing as seed data (in webtools import XML)
<ControllerInjection injectUrl="component://controllerinjectex/webapp/controllerinjectex/WEB-INF/controller.xml"
injectIntoUrl="component://crmsfa/webapp/crmsfa/WEB-INF/controller.xml" sequenceNum="99" />
* access ''/crmsfa/control/echo'' in a browser
* note: ''opentaps/controllerinjectex/data/InjectData.xml'' also contains an example Shortcut which will be inserted in the crmsfa home tab shortcut group for access to this page

Note that with injection its ''WEB-INF/web.xml'' is no longer needed.

The result will be the same as the previous and more complex process:
# commenting the webapp to customize mount point in its ''ofbiz-component.xml''
# creating a webapp in the custom component (''WEB-INF/web.xml'' and mount point in the ''ofbiz-component.xml'', with the same name as the original webapp mount point)
# including the controller to customize (eg: ''component://crmsfa/webapp/crmsfa/WEB-INF/controller.xml'') in the custom component controller

Customizing opentaps Applications

2011-02-08T13:48:18Z

Jwickers: /* Controller Injection */

Frequently you will need to customize opentaps applications, such as change the tabs or shortcuts at the top or add new screens. Beginning with opentaps 1.5, you can make these changes without affecting the core opentaps code, making it easier for you to upgrade later when new versions of opentaps becomes available.

opentaps 1.5 supports the following new features to help you customize its applications:
* The tabs and shortcuts available are now stored in the database, so you can rearrange or change the user interface labels.
* Other user interface elements are also now defined in configuration database entities.
* You can "inject" new controller entries into opentaps applications, making it possible to load your screens and actions into an opentaps application.

__TOC__

==Webapp User Interface Database Entities==

'''OpentapsWebApps''' : defines a webapp (eg: crmsfa, financials), they are listed in the top navigation menu.
* linkUrl should correspond to the home page of the application (eg: /crmsfa/control/main).
* shortName, description, applicationName, imageUrl and imageHoverUrl are used in the opentaps main home page (accessed at /opentaps)
* shortName is also used in top navigation menu as the link label
* sequenceNum is to specify the display order in the nvaigation menu and the opentaps main home page

'''OpentapsWebAppTab''' : a webapp may have multiple tabs (eg: home, orders, accounts .. in crmsfa), they are listed as tabs in the webapp below the top navigation menu.
* uiLabel is the label of the tab, this can use a localized string when present in one of the localized resources, else will be displayed as is
* linkUrl can be just the request name in the application, or if isExternal is set to Y it will be used as is (eg: /opentaps, http://www.example.com/somewhere for external urls)
* sequenceNum is to specify the display order
* securityModule, securityAction, handlerMethod, handlerParameter see below

'''OpentapsShortcutGroup''' : a shortcut group is a small menu in the left column of the page with a title and a list of shortcuts (links)
* uiLabel is the label of the title of the group, this can use a localized string when present in one of the localized resources, else will be displayed as is. If left blank it defaults to the localized string "Shortcuts"
* sequenceNum is to specify the display order
* securityModule, securityAction, handlerMethod, handlerParameter see below

'''OpentapsShortcut''' : a link in a shortcut group
* uiLabel is the label of the shortcut, this can use a localized string when present in one of the localized resources, else will be displayed as is
* linkUrl can be just the request name in the application, or if isExternal is set to Y it will be used as is (eg: /opentaps, http://www.example.com/somewhere for external urls)
* sequenceNum is to specify the display order
* securityModule, securityAction, handlerMethod, handlerParameter see below

===String substitution===

In OpentapsWebAppTab, OpentapsShortcutGroup and OpentapsShortcut the linkUrl and uiLabel supports automatic substitutions according to the current context so "${foo}" will be changed into the context value of "foo".

===Permission===

OpentapsWebAppTab, OpentapsShortcutGroup and OpentapsShortcut all have the securityModule and securityAction fields to specify a basic permission the user must have in order to see the corresponding entity. eg: securityModule="CRMSFA_CONTACTS" securityAction="VIEW" for the contact tab.

Note: this only affects the display on the page, not actual access control (yet).

===Handlers===

In some cases the basic permission will not be enough, or we need more control over what should actually be displayed or not. For this the handlerMethod and handlerParameter fields can be used.

handlerMethod is java method that takes a context Map (Map<String, Object>) and the entity being checked (OpentapsWebAppTab or OpentapsShortcutGroup or OpentapsShortcut or a generic <T extends EntityInterface>) as parameters, and returns the given entity.
This method is called before display and is then free to modify any part of the entity like url, label which will then affect how it is displayed to the current user; and if the entity should not be displayed it can simply return null.
handlerParameter can then be used to provide data to a generic handler (like a complex permission to check, a view preference, etc ...)

Example of handlers:

* ''org.opentaps.warehouse.security.WarehouseSecurity.checkFacilityPermission'' : checks the current user permission on the current facility (as selected when entering the warehouse application) against the permission set in handlerParameter
* ''org.opentaps.webapp.handlers.CommonHandlers.checkSessionValueAbsent'' : checks if the user session does not contain the key specified by handlerParameter (or has a null value)
* ''org.opentaps.webapp.handlers.CommonHandlers.checkSessionValuePresent'' : checks if the user session contains the key specified by handlerParameter (has a non null value)
* ''org.opentaps.webapp.handlers.CommonHandlers.checkHasNoCart'' : check the current user session does not have a shopping cart
* ''org.opentaps.webapp.handlers.CommonHandlers.checkHasCart'' : check the current user session has a shopping cart
* ''org.opentaps.webapp.handlers.CommonHandlers.checkBoolean'' : check the current context has a value named by handlerParameter as a boolean True or a string Y/y
* ''org.opentaps.webapp.handlers.CommonHandlers.checkViewPreferenceForTab'' : check the current user view preference in the current tab; handlerParameter should contain 2 colon separated values: prefType:valueToCheck:default (eg: "MY_OR_TEAM_ACCOUNTS:MY_VALUES:TEAM_VALUES" checks if the MY_OR_TEAM_ACCOUNTS view preference is set to MY_VALUES, and use TEAM_VALUES as default if the view preference is empty)

==Controller Injection==

The '''ControllerInject''' entity allows to inject a controller xml file into another. Usually this is done to customize one of the existing application without modifying their controller file directly, and so keeping the customization isolated from the base code.

The ''injectUrl'' field specify the url of the controller to inject, and ''injectIntoUrl'' the target controller.

For example see the ''opentaps/controllerinjectex'' component, activate it by:
* add ''<load-component component-location="controllerinjectex"/>'' in ''opentaps/component-load.xml''

Then either mount is a normal webapp:
* uncomment the ''webapp'' definition in its ''ofbiz-component.xml''
* access ''/controllerinjectex/'' in a browser

Or use the controller injection by:
* importing as seed data (in webtools import XML)
<ControllerInjection injectUrl="component://controllerinjectex/webapp/controllerinjectex/WEB-INF/controller.xml"
injectIntoUrl="component://crmsfa/webapp/crmsfa/WEB-INF/controller.xml" sequenceNum="99" />
* access ''/crmsfa/control/echo'' in a browser
* note: ''opentaps/controllerinjectex/data/InjectData.xml'' also contains an example Shortcut which will be inserted in the crmsfa home tab shortcut group for access to this page

Note that with injection its ''WEB-INF/web.xml'' is no longer needed.

The result will be the same as the previous and more complex process:
# commenting the webapp to customize mount point in its ''ofbiz-component.xml''
# creating a webapp in the custom component (''WEB-INF/web.xml'' and mount point in the ''ofbiz-component.xml'', with the same name as the original webapp mount point)
# including the controller to customize (eg: ''component://crmsfa/webapp/crmsfa/WEB-INF/controller.xml'') in the custom component controller

Customizing opentaps Applications

2011-02-08T13:39:47Z

Jwickers: /* Controller Injection */

Frequently you will need to customize opentaps applications, such as change the tabs or shortcuts at the top or add new screens. Beginning with opentaps 1.5, you can make these changes without affecting the core opentaps code, making it easier for you to upgrade later when new versions of opentaps becomes available.

opentaps 1.5 supports the following new features to help you customize its applications:
* The tabs and shortcuts available are now stored in the database, so you can rearrange or change the user interface labels.
* Other user interface elements are also now defined in configuration database entities.
* You can "inject" new controller entries into opentaps applications, making it possible to load your screens and actions into an opentaps application.

__TOC__

==Webapp User Interface Database Entities==

'''OpentapsWebApps''' : defines a webapp (eg: crmsfa, financials), they are listed in the top navigation menu.
* linkUrl should correspond to the home page of the application (eg: /crmsfa/control/main).
* shortName, description, applicationName, imageUrl and imageHoverUrl are used in the opentaps main home page (accessed at /opentaps)
* shortName is also used in top navigation menu as the link label
* sequenceNum is to specify the display order in the nvaigation menu and the opentaps main home page

'''OpentapsWebAppTab''' : a webapp may have multiple tabs (eg: home, orders, accounts .. in crmsfa), they are listed as tabs in the webapp below the top navigation menu.
* uiLabel is the label of the tab, this can use a localized string when present in one of the localized resources, else will be displayed as is
* linkUrl can be just the request name in the application, or if isExternal is set to Y it will be used as is (eg: /opentaps, http://www.example.com/somewhere for external urls)
* sequenceNum is to specify the display order
* securityModule, securityAction, handlerMethod, handlerParameter see below

'''OpentapsShortcutGroup''' : a shortcut group is a small menu in the left column of the page with a title and a list of shortcuts (links)
* uiLabel is the label of the title of the group, this can use a localized string when present in one of the localized resources, else will be displayed as is. If left blank it defaults to the localized string "Shortcuts"
* sequenceNum is to specify the display order
* securityModule, securityAction, handlerMethod, handlerParameter see below

'''OpentapsShortcut''' : a link in a shortcut group
* uiLabel is the label of the shortcut, this can use a localized string when present in one of the localized resources, else will be displayed as is
* linkUrl can be just the request name in the application, or if isExternal is set to Y it will be used as is (eg: /opentaps, http://www.example.com/somewhere for external urls)
* sequenceNum is to specify the display order
* securityModule, securityAction, handlerMethod, handlerParameter see below

===String substitution===

In OpentapsWebAppTab, OpentapsShortcutGroup and OpentapsShortcut the linkUrl and uiLabel supports automatic substitutions according to the current context so "${foo}" will be changed into the context value of "foo".

===Permission===

OpentapsWebAppTab, OpentapsShortcutGroup and OpentapsShortcut all have the securityModule and securityAction fields to specify a basic permission the user must have in order to see the corresponding entity. eg: securityModule="CRMSFA_CONTACTS" securityAction="VIEW" for the contact tab.

Note: this only affects the display on the page, not actual access control (yet).

===Handlers===

In some cases the basic permission will not be enough, or we need more control over what should actually be displayed or not. For this the handlerMethod and handlerParameter fields can be used.

handlerMethod is java method that takes a context Map (Map<String, Object>) and the entity being checked (OpentapsWebAppTab or OpentapsShortcutGroup or OpentapsShortcut or a generic <T extends EntityInterface>) as parameters, and returns the given entity.
This method is called before display and is then free to modify any part of the entity like url, label which will then affect how it is displayed to the current user; and if the entity should not be displayed it can simply return null.
handlerParameter can then be used to provide data to a generic handler (like a complex permission to check, a view preference, etc ...)

Example of handlers:

* ''org.opentaps.warehouse.security.WarehouseSecurity.checkFacilityPermission'' : checks the current user permission on the current facility (as selected when entering the warehouse application) against the permission set in handlerParameter
* ''org.opentaps.webapp.handlers.CommonHandlers.checkSessionValueAbsent'' : checks if the user session does not contain the key specified by handlerParameter (or has a null value)
* ''org.opentaps.webapp.handlers.CommonHandlers.checkSessionValuePresent'' : checks if the user session contains the key specified by handlerParameter (has a non null value)
* ''org.opentaps.webapp.handlers.CommonHandlers.checkHasNoCart'' : check the current user session does not have a shopping cart
* ''org.opentaps.webapp.handlers.CommonHandlers.checkHasCart'' : check the current user session has a shopping cart
* ''org.opentaps.webapp.handlers.CommonHandlers.checkBoolean'' : check the current context has a value named by handlerParameter as a boolean True or a string Y/y
* ''org.opentaps.webapp.handlers.CommonHandlers.checkViewPreferenceForTab'' : check the current user view preference in the current tab; handlerParameter should contain 2 colon separated values: prefType:valueToCheck:default (eg: "MY_OR_TEAM_ACCOUNTS:MY_VALUES:TEAM_VALUES" checks if the MY_OR_TEAM_ACCOUNTS view preference is set to MY_VALUES, and use TEAM_VALUES as default if the view preference is empty)

==Controller Injection==

The '''ControllerInject''' entity allows to inject a controller xml file into another. Usually this is done to customize one of the existing application without modifying their controller file directly, and so keeping the customization isolated from the base code.

The ''injectUrl'' field specify the url of the controller to inject, and ''injectIntoUrl'' the target controller.

Example:

<ControllerInjection injectUrl="component://controllerinjectex/webapp/controllerinjectex/WEB-INF/controller.xml"
injectIntoUrl="component://crmsfa/webapp/crmsfa/WEB-INF/controller.xml" sequenceNum="99" />

The result will be the same as the previous and more complex process:
# commenting the webapp to customize mount point in its ''ofbiz-component.xml''
# creating a webapp in the custom component (''WEB-INF/web.xml'' and mount point in the ''ofbiz-component.xml'', with the same name as the original webapp mount point)
# including the controller to customize (eg: ''component://crmsfa/webapp/crmsfa/WEB-INF/controller.xml'') in the custom component controller

Customizing opentaps Applications

2011-02-08T13:17:27Z

Jwickers: /* Webapp User Interface Database Entities */

Frequently you will need to customize opentaps applications, such as change the tabs or shortcuts at the top or add new screens. Beginning with opentaps 1.5, you can make these changes without affecting the core opentaps code, making it easier for you to upgrade later when new versions of opentaps becomes available.

opentaps 1.5 supports the following new features to help you customize its applications:
* The tabs and shortcuts available are now stored in the database, so you can rearrange or change the user interface labels.
* Other user interface elements are also now defined in configuration database entities.
* You can "inject" new controller entries into opentaps applications, making it possible to load your screens and actions into an opentaps application.

__TOC__

==Webapp User Interface Database Entities==

'''OpentapsWebApps''' : defines a webapp (eg: crmsfa, financials), they are listed in the top navigation menu.
* linkUrl should correspond to the home page of the application (eg: /crmsfa/control/main).
* shortName, description, applicationName, imageUrl and imageHoverUrl are used in the opentaps main home page (accessed at /opentaps)
* shortName is also used in top navigation menu as the link label
* sequenceNum is to specify the display order in the nvaigation menu and the opentaps main home page

'''OpentapsWebAppTab''' : a webapp may have multiple tabs (eg: home, orders, accounts .. in crmsfa), they are listed as tabs in the webapp below the top navigation menu.
* uiLabel is the label of the tab, this can use a localized string when present in one of the localized resources, else will be displayed as is
* linkUrl can be just the request name in the application, or if isExternal is set to Y it will be used as is (eg: /opentaps, http://www.example.com/somewhere for external urls)
* sequenceNum is to specify the display order
* securityModule, securityAction, handlerMethod, handlerParameter see below

'''OpentapsShortcutGroup''' : a shortcut group is a small menu in the left column of the page with a title and a list of shortcuts (links)
* uiLabel is the label of the title of the group, this can use a localized string when present in one of the localized resources, else will be displayed as is. If left blank it defaults to the localized string "Shortcuts"
* sequenceNum is to specify the display order
* securityModule, securityAction, handlerMethod, handlerParameter see below

'''OpentapsShortcut''' : a link in a shortcut group
* uiLabel is the label of the shortcut, this can use a localized string when present in one of the localized resources, else will be displayed as is
* linkUrl can be just the request name in the application, or if isExternal is set to Y it will be used as is (eg: /opentaps, http://www.example.com/somewhere for external urls)
* sequenceNum is to specify the display order
* securityModule, securityAction, handlerMethod, handlerParameter see below

===String substitution===

In OpentapsWebAppTab, OpentapsShortcutGroup and OpentapsShortcut the linkUrl and uiLabel supports automatic substitutions according to the current context so "${foo}" will be changed into the context value of "foo".

===Permission===

OpentapsWebAppTab, OpentapsShortcutGroup and OpentapsShortcut all have the securityModule and securityAction fields to specify a basic permission the user must have in order to see the corresponding entity. eg: securityModule="CRMSFA_CONTACTS" securityAction="VIEW" for the contact tab.

Note: this only affects the display on the page, not actual access control (yet).

===Handlers===

In some cases the basic permission will not be enough, or we need more control over what should actually be displayed or not. For this the handlerMethod and handlerParameter fields can be used.

handlerMethod is java method that takes a context Map (Map<String, Object>) and the entity being checked (OpentapsWebAppTab or OpentapsShortcutGroup or OpentapsShortcut or a generic <T extends EntityInterface>) as parameters, and returns the given entity.
This method is called before display and is then free to modify any part of the entity like url, label which will then affect how it is displayed to the current user; and if the entity should not be displayed it can simply return null.
handlerParameter can then be used to provide data to a generic handler (like a complex permission to check, a view preference, etc ...)

Example of handlers:

* ''org.opentaps.warehouse.security.WarehouseSecurity.checkFacilityPermission'' : checks the current user permission on the current facility (as selected when entering the warehouse application) against the permission set in handlerParameter
* ''org.opentaps.webapp.handlers.CommonHandlers.checkSessionValueAbsent'' : checks if the user session does not contain the key specified by handlerParameter (or has a null value)
* ''org.opentaps.webapp.handlers.CommonHandlers.checkSessionValuePresent'' : checks if the user session contains the key specified by handlerParameter (has a non null value)
* ''org.opentaps.webapp.handlers.CommonHandlers.checkHasNoCart'' : check the current user session does not have a shopping cart
* ''org.opentaps.webapp.handlers.CommonHandlers.checkHasCart'' : check the current user session has a shopping cart
* ''org.opentaps.webapp.handlers.CommonHandlers.checkBoolean'' : check the current context has a value named by handlerParameter as a boolean True or a string Y/y
* ''org.opentaps.webapp.handlers.CommonHandlers.checkViewPreferenceForTab'' : check the current user view preference in the current tab; handlerParameter should contain 2 colon separated values: prefType:valueToCheck:default (eg: "MY_OR_TEAM_ACCOUNTS:MY_VALUES:TEAM_VALUES" checks if the MY_OR_TEAM_ACCOUNTS view preference is set to MY_VALUES, and use TEAM_VALUES as default if the view preference is empty)

==Controller Injection==

Configuring Authorize.NET

2010-08-26T18:21:00Z

Jwickers: /* Testing Your Setup */

== Testing Your Setup ==

[http://reseller.authorize.net/application/?id=5553974 Authorize.NET] is a payment gateway for processing credit card and e-check payments. It has a live server and a testing server. Both servers behave in exactly the same way with the exception that the testing server does not perform any real financial transactions. Hence, the testing server should be used to do development work and to trial run Opentaps features such as order fulfillment to see how they behave.

The testing server requires a testing account, which is distinct from a real account. A testing account can be obtained from,

http://developer.authorize.net/testaccount/

Next, you will need to configure payment.properties for testing. The following setup is recommended,

<pre>
payment.authorizedotnet.url=https://test.authorize.net/gateway/transact.dll
payment.authorizedotnet.trankey= Transaction key of the testing account
payment.authorizedotnet.test=FALSE
payment.authorizedotnet.logging=TRUE
payment.authorizedotnet.login= API Login key of the testing account
</pre>

The test parameter should be set to FALSE except for testing special things that will be described below. Setting it to true will turn on Test Mode, which is a special state that prevents transaction IDs from being generated and affects both the live and testing server. This is generally not useful, except in specific cases as we'll come to in the next section. If unsure, always set test to FALSE.

Then you will need to add the certificate from https://secure.authorize.net/ if you use production setup or https://test.authorize.net for testing setup.

Go to that page with a navigator, then export the SSL certificate of the page.
Then on the server add it to your JDK default keystore:

cd $JAVA_HOME/jre/lib/security
keytool -import -trustcacerts -file secure.authorize.net.cert -alias AUTHORIZE_NET -keystore cacerts

=== Testing Specific Gateway Failures ===

Suppose you wish to see what happens when there is an AVS address verification failure (code 27) that results in an authorization being declined. We can trigger the test server to return this by using a special VISA credit card number '''4222222222222''' and an authorization amount equal to the error code ($27.00). Because the CC validation code will not let you create this number, you'll have to create a CreditCard record by hand and a PaymentMethod for it.

Make the following change to '''payment.properties''',

<pre>
payment.authorizedotnet.test=TRUE
</pre>

Restart opentaps and create an order with an offline payment. Cancel the payment and add a new payment for the amount you want to test, in this example $27. Opentaps will automatically authorize the payment, which should trigger the desired transaction error code 27,

<pre>
(TESTMODE) The transaction resulted in an AVS mismatch. The address provided does not match billing address of cardholder.
</pre>

When you're done, be sure to set '''payment.authorizedotnet.test''' back to '''FALSE'''.

Release Testing

2010-08-13T09:18:54Z

Jwickers: /* Release Packaging */

==Release Testing==

These are some general tests, which should be performed prior to releases:

* checkout opentaps from the SVN

* Make sure that ant run-install works.
* Then check the basic functionality for doing the following:
** CRM - create leads, qualify them, convert them to accounts, create notes, opportunities, tasks, events
** Catalog - create new categories and products, make sure they show up on ecommerce
** ecommerce - see new products, sign up as new customer, place orders, see order history
** purchasing -- creating new supplier with contact information
** catalog - create purchasing information for supplier
** purchasing -- create purchase orders for product
** warehouse -- receive products on purchase orders, verify that the inventory in the warehouse has increased.
** warehouse - Pack & ship orders, verify that the inventory has decreased.
** warehouse -- create a production run for PROD_COST, schedule and confirm it, make sure that it shows up on the calendar, complete the production run, and make sure that the inventory for PROD_COST has increased and the inventory for MAT_A_COST and MAT_B_COST have decreased.
** Order - create sales and purchase orders
** Financials - see invoices and trial balances. Trial balances should always be equal on debit & credit.

* Make sure ant run-tests works

==Release Packaging==

* from a fresh checkout, run ant run-install
* change the release version in framework/common/config/CommonUiLabels.xml
* make sure the GWT configuration is set to compile for all locals and all browser in opentaps-common/src/common/org/opentaps/gwt/common/common.gwt.xml
** uncomment all extend-property
** comment out <set-property name="user.agent" ..>
* don't forget to regenerate the labels after that
* run ant (so the GWT modules are rebuilt)
* remove logs in runtime/logs
* make a zip file with the root directory which should be opentaps-{version} (for example opentaps-1.0.2). Also note that we do include the .svn directories in the release (pointing to the trunk).
* unzip the file and verify that the data has been installed

'''Make sure your package contains the demo data installed in localderby database.'''

Release Testing

2010-08-13T09:17:48Z

Jwickers: /* Release Packaging */

==Release Testing==

These are some general tests, which should be performed prior to releases:

* checkout opentaps from the SVN

* Make sure that ant run-install works.
* Then check the basic functionality for doing the following:
** CRM - create leads, qualify them, convert them to accounts, create notes, opportunities, tasks, events
** Catalog - create new categories and products, make sure they show up on ecommerce
** ecommerce - see new products, sign up as new customer, place orders, see order history
** purchasing -- creating new supplier with contact information
** catalog - create purchasing information for supplier
** purchasing -- create purchase orders for product
** warehouse -- receive products on purchase orders, verify that the inventory in the warehouse has increased.
** warehouse - Pack & ship orders, verify that the inventory has decreased.
** warehouse -- create a production run for PROD_COST, schedule and confirm it, make sure that it shows up on the calendar, complete the production run, and make sure that the inventory for PROD_COST has increased and the inventory for MAT_A_COST and MAT_B_COST have decreased.
** Order - create sales and purchase orders
** Financials - see invoices and trial balances. Trial balances should always be equal on debit & credit.

* Make sure ant run-tests works

==Release Packaging==

* from a fresh checkout, run ant run-install
* change the release version in framework/common/config/CommonUiLabels.xml
* make sure the GWT configuration is set to compile for all locals and all browser in opentaps-common/src/common/org/opentaps/gwt/common/common.gwt.xml
** uncomment all extend-property
** comment out <set-property name="user.agent" ..>
* don't forget to regenerate the labels after that
* remove logs in runtime/logs
* make a zip file with the root directory which should be opentaps-{version} (for example opentaps-1.0.2). Also note that we do include the .svn directories in the release (pointing to the trunk).
* unzip the file and verify that the data has been installed

'''Make sure your package contains the demo data installed in localderby database.'''

Release Testing

2010-08-13T09:16:30Z

Jwickers: /* Release Testing */

==Release Testing==

These are some general tests, which should be performed prior to releases:

* checkout opentaps from the SVN

* Make sure that ant run-install works.
* Then check the basic functionality for doing the following:
** CRM - create leads, qualify them, convert them to accounts, create notes, opportunities, tasks, events
** Catalog - create new categories and products, make sure they show up on ecommerce
** ecommerce - see new products, sign up as new customer, place orders, see order history
** purchasing -- creating new supplier with contact information
** catalog - create purchasing information for supplier
** purchasing -- create purchase orders for product
** warehouse -- receive products on purchase orders, verify that the inventory in the warehouse has increased.
** warehouse - Pack & ship orders, verify that the inventory has decreased.
** warehouse -- create a production run for PROD_COST, schedule and confirm it, make sure that it shows up on the calendar, complete the production run, and make sure that the inventory for PROD_COST has increased and the inventory for MAT_A_COST and MAT_B_COST have decreased.
** Order - create sales and purchase orders
** Financials - see invoices and trial balances. Trial balances should always be equal on debit & credit.

* Make sure ant run-tests works

==Release Packaging==

* from a fresh checkout, run ant run-install
* change the release version in framework/common/config/CommonUiLabels.xml
* make sure the GWT configuration is set to compile for all locals and all browser in
** uncomment all extend-property
** comment out <set-property name="user.agent" ..>
* don't forget to regenerate the labels after that
* remove logs in runtime/logs
* make a zip file with the root directory which should be opentaps-{version} (for example opentaps-1.0.2). Also note that we do include the .svn directories in the release (pointing to the trunk).
* unzip the file and verify that the data has been installed

'''Make sure your package contains the demo data installed in localderby database.'''

Release Testing

2010-08-13T09:15:45Z

Jwickers: /* Release Testing */

==Release Testing==

These are some general tests, which should be performed prior to releases:

* checkout opentaps from the SVN

* Make sure that ant run-install works.
* Then check the basic functionality for doing the following:
** CRM - create leads, qualify them, convert them to accounts, create notes, opportunities, tasks, events
** Catalog - create new categories and products, make sure they show up on ecommerce
** ecommerce - see new products, sign up as new customer, place orders, see order history
** purchasing -- creating new supplier with contact information
** catalog - create purchasing information for supplier
** purchasing -- create purchase orders for product
** warehouse -- receive products on purchase orders, verify that the inventory in the warehouse has increased.
** warehouse - Pack & ship orders, verify that the inventory has decreased.
** warehouse -- create a production run for PROD_COST, schedule and confirm it, make sure that it shows up on the calendar, complete the production run, and make sure that the inventory for PROD_COST has increased and the inventory for MAT_A_COST and MAT_B_COST have decreased.
** Order - create sales and purchase orders
** Financials - see invoices and trial balances. Trial balances should always be equal on debit & credit.

* Make sure ant run-tests works

* make opentaps release package
** from a fresh checkout, run ant run-install
** change the release version in framework/common/config/CommonUiLabels.xml
** make sure the GWT configuration is set to compile for all locals and all browser in
*** uncomment all extend-property
*** comment out <set-property name="user.agent" ..>
* don't forget to regenerate the labels after that
** remove logs in runtime/logs
** make a zip file with the root directory which should be opentaps-{version} (for example opentaps-1.0.2). Also note that we do include the .svn directories in the release (pointing to the trunk).
** unzip the file and verify that the data has been installed

'''Make sure your package contains the demo data installed in localderby database.'''

Release Testing

2010-08-13T08:41:33Z

Jwickers: /* Release Testing */

==Release Testing==

These are some general tests, which should be performed prior to releases:

* checkout opentaps from the SVN

* Make sure that ant run-install works.
* Then check the basic functionality for doing the following:
** CRM - create leads, qualify them, convert them to accounts, create notes, opportunities, tasks, events
** Catalog - create new categories and products, make sure they show up on ecommerce
** ecommerce - see new products, sign up as new customer, place orders, see order history
** purchasing -- creating new supplier with contact information
** catalog - create purchasing information for supplier
** purchasing -- create purchase orders for product
** warehouse -- receive products on purchase orders, verify that the inventory in the warehouse has increased.
** warehouse - Pack & ship orders, verify that the inventory has decreased.
** warehouse -- create a production run for PROD_COST, schedule and confirm it, make sure that it shows up on the calendar, complete the production run, and make sure that the inventory for PROD_COST has increased and the inventory for MAT_A_COST and MAT_B_COST have decreased.
** Order - create sales and purchase orders
** Financials - see invoices and trial balances. Trial balances should always be equal on debit & credit.

* Make sure ant run-tests works
* Change the release version in framework/common/config/CommonUiLabels.xml
* make sure the GWT configuration is set to compile for all locals and all browser in
** uncomment all extend-property
** comment out <set-property name="user.agent" ..>
* don't forget to regenerate the labels after that

* make opentaps release package
** from a fresh checkout, run ant run-install
** remove logs in runtime/logs
** make a zip file with the root directory which should be opentaps-{version} (for example opentaps-1.0.2). Also note that we do include the .svn directories in the release (pointing to the trunk).
** unzip the file and verify that the data has been installed

'''Make sure your package contains the demo data installed in localderby database.'''

How to Use Git: a Tutorial

2010-08-11T17:05:55Z

Jwickers: /* Merge Request */

This document is a work in progress.

__TOC__

==General Concepts==

[http://git-scm.com/ Git] is a free open source distributed version control system designed to handle everything from small to very large projects with speed and efficiency...once you learn how to use it.

Git can be (more than) a little confusing at first when coming from a Subversion background. Let's first try to compare subversion and git:
* it is '''distributed''': every ''checkout'' is actually a clone of the master repository, this means that there is no higher authority or single point of failure. Effectively every developer has it own repository with its own branches and own commits.
* because of that, it can also be describe as '''disconnected''': one does not need to access the master repository in order to commit, branch, merge or review the history.
* this makes all operations that would normally use the Subversion server __usable__ (checking commit log, blame, branching and merging).
* it is '''storage efficient''': the Opentaps repository in Git including 1.0.0 / 1.4 / 1.0 and all the branches and tags takes around 900Mo, typically a SVN checkout of 1.4 alone would be more than 600M, multiply this be each branch and by each tag ...

Probably one of the most important point is '''branching'''. Because Subversion branches are difficult to merge and expensive to create (one need to do a whole ''checkout'' to get a branch) they are mostly used as dead branches.

In comparison, in Git branches are very easy to create and merge back. In the git way of thinking, they are "free," and because they are local they are actually used all the time. The reason why a complete Git repository of opentaps is only 900Mo instead of a few gigabyte is because they all share a lot of common content.

Git branches are typically used for:
* local only configuration
* unit of work (tickets)
* client and sub projects

=== Local Configuration Branch ===

One of the first thing that we all do is the configuration of the database in `entityengine.xml`, and in subversion we have to lock the file else it ends up accidentally modified.

In Git one could instead use a '''configuration''' branch.

This branch can be considered a floating branch, because we want to apply it on top of whatever branch we are currently working on.
<pre>
*-----[master]----[work]----[configuration]
</pre>

=== Unit of work Branch ===

Let's say you want to work on a feature. With git, You can create a branch for your feature, work on it, and then merge it back to the main branch. A typical workflow is, from
<pre>
*-----[master]
</pre>

Create a working branch:
<pre>
*-----[master][1234-some-ticket]
</pre>

Make some commits, so your 1234-some-ticket branch advances further:
<pre>
*-----[master]---[1234-some-ticket]
</pre>

Then push the branch on `origin` for review, and have the reviewer merge it:
<pre>
*-----o------[master]
|
\---[1234-some-ticket]

master> git merge 1234-some-ticket

*-----o-----------------------(1234 merged)[master]
| |
\---[1234-some-ticket]/
</pre>

If we do not want the reviewer to do any conflict resolution and want to do it ourselves, we can merge the master into our 1234-some-ticket branch first:
<pre>
*-----o------[master]
|
\---[1234-some-ticket]

1234-some-ticket> git merge master

*-----o------[master]
| |
\------------(master merged)[1234-some-ticket]
<</pre>

Note that all of this do not mean that the branch has be local until ready, it can be pushed little by little.

We can then push it back to the master. This only produce one merge commit in the `master` branch per ticket / feature.
This makes it easier for third parties to follow.

=== Client and Sub Projects ===

Typically clients implementing opentaps or developers creating a project based on it use their own subversion repository created from a checkout of opentpas. Luckily the architecture of opentaps allow them to only store a custom hot-deploy component, but sometimes this is still a bit limited and as we know they end up touching code outside of there own components. Finally they sometimes request features / bug fixes that we implement in both our and their repository.

Having the ability to clone our repository and branch it easily means that the changes they make are contained in their branch. It also makes it easier for them to receive updates from the main opentaps repository. Finally, by setting up their repository as a new remote (eg: `client-origin`), you can have many clients in the same local repository (saving some disk space in the process). All that is needed is an SSH access, which is much easier to setup than a SVN server.

<pre>
*--o--o-----------------------------[origin/master]
| | | |
| | | |
| \----------[client-origin1/client]-[merged]
| |
| |
\---------[client-origin2/client]-[merged]
</pre>

==Using Git==

Now let's actually try to use git.

===Getting the Code===

First, let's take a look at the basic process of getting the code from git and making some local changes. Getting the code is a lot like subversion, at least on the surface. You would use the <tt>git clone</tt> command to pull the code from the remote repository to your local computer:
<pre>
$ git clone git://gitorious.org/opentaps/opentaps.git git-opentaps
Initialized empty Git repository in /Users/sichen/Documents/workspace/git-opentaps/.git/
remote: Counting objects: 78173, done.
remote: Compressing objects: 100% (14699/14699), done.
remote: Total 78173 (delta 57124), reused 77443 (delta 56698)
Receiving objects: 100% (78173/78173), 219.74 MiB | 303 KiB/s, done.
Resolving deltas: 100% (57124/57124), done.
Checking out files: 100% (15107/15107), done.
</pre>

Now, let's imagine that you modified a file, such as <tt>framework/entity/config/entityengine.xml</tt>, and changed it to use mysql instead of the embedded Derby database. You can use <tt>git status</tt> to get a list of the files that have been modified:
<pre>
$ git status
# On branch master
# Changed but not updated:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: framework/entity/config/entityengine.xml
#
no changes added to commit (use "git add" and/or "git commit -a")
</pre>

<tt>git diff</tt> will show you the actual modifications, or differences:
<pre>
$ git diff
diff --git a/framework/entity/config/entityengine.xml b/framework/entity/config/entityengine.xml
index 652c6fc..d6d341e 100644
--- a/framework/entity/config/entityengine.xml
+++ b/framework/entity/config/entityengine.xml
@@ -51,7 +51,7 @@ access. For a detailed description see the core/docs/entityconfig.html file.
<connection-factory class="org.ofbiz.entity.connection.DBCPConnectionFactory"/>

<delegator name="default" entity-model-reader="main" entity-group-reader="main" entity-eca-reader="main" distributed-cache-clear-enabled="false">
- <group-map group-name="org.ofbiz" datasource-name="localderby"/>
+ <group-map group-name="org.ofbiz" datasource-name="localmysql"/>
<group-map group-name="org.ofbiz.olap" datasource-name="localderbyolap"/>
<group-map group-name="org.opentaps.analytics" datasource-name="analytics"/>
<group-map group-name="org.opentaps.testing" datasource-name="testing"/>
</pre>
etc. etc.

===Updating===

To bring your clone up to date with the remote main opentaps repository,

<pre>
$ git fetch
</pre>

This will get updates from all the branches on the remote repository and pull them to your local clone. If you have created local branches from your remote branches, then you would need to update your local branches from the remote branches that were updated (see below):

$ git rebase origin/1447 1447

If however your local branches have changes, git will complain:
cannot rebase: you have unstaged changes
M framework/entity/config/entityengine.xml

If that's the case, you will have to "stash" your changes for the moment:
<pre>
$ git stash
$ git rebase origin/1447 1447
</pre>

===Committing Your Changes===

To commit your changes, you must first add the change files to the list of files to commit with <tt>git add</tt>:
$ git add opentaps/opentaps-common/src/common/org/opentaps/gwt/common/server/lookup/PartyLookupService.java

This will move the file into the "Changes to be committed" list of files when you do your <tt>git status</tt>.

Note that <tt>git add</tt> is recursive, so if you
$ git add opentaps/search/src/

It will add all files which are in subdirectories of <tt>opentaps/search/src/</tt>

Once you have added your files, <tt>git commit</tt> will allow you to save your changes, or "commit" them.
<pre>
$ git commit -a
[master 4516382] Change configuration to use mysql
</pre>

'''Here's the big difference:''' After you have committed your change, it is committed to your local clone, '''not''' to the master git repository of opentaps. This means that it is still available to you, and to anybody who makes a clone of your git repository, but not to anybody who is cloning the main opentaps repository.

After you commit, you can get a history of your changes with <tt>git log</tt>:
<pre>
$ git log framework/entity/config/entityengine.xml
commit 4516382fb3d17da5a2bdccd1942b01636ea08e4d
Author: si chen <sichen@si-chens-imac.gateway.2wire.net>
Date: Tue Apr 13 11:32:56 2010 -0700

Change configuration to use mysql

commit b5bf829383d261f7eb2e4c733568dbcce65868f7
Author: sparksun <sparksun@d3523486-f5fe-0310-a41a-a15a4e76f3c7>
Date: Thu Jan 7 13:51:57 2010 +0000

#1315 add useOldAliasMetadataBehavior parameter in mysql jdbc url for avoid hibernate cannot find column view entity

git-svn-id: svn://svn.opentaps.org/opentaps_all/versions/1.4/trunk@14503 d3523486-f5fe-0310-a41a-a15a4e76f3c7

commit 6678504157a4234d051292a336bc623d83107ff2
Author: jwickers <jwickers@d3523486-f5fe-0310-a41a-a15a4e76f3c7>
Date: Fri Nov 27 04:12:00 2009 +0000

Reset default entity config to use Derby

git-svn-id: svn://svn.opentaps.org/opentaps_all/versions/1.4/trunk@14071 d3523486-f5fe-0310-a41a-a15a4e76f3c7
</pre>

Note that unlike subversion, you can see a log of all the changes of the file even before your branch was created.

===Reverting a Changed File===

What if you want to revert your changes to a file and go back to the way it was on your local repository? In git, you would use <tt>checkout</tt>, like this:
git checkout <file>

Thanks to http://norbauer.com/notebooks/code/notes/git-revert-reset-a-single-file for this tip!

===Your Stash===

To see the changes you have stashed away,
$ git stash list

To see which files have been stashed away, use
$ git stash show

and to get it back out of the stash and apply the stashed away changes to your current working branch,
$ git stash pop

(Note its' better to <tt>git stash pop</tt> than <tt>git stash apply</tt>, or your temporary changes will stay around and accumulate until it's confusing. In which case, you can <tt>git stash drop</tt> to get rid of them all and start over again.)

===Pushing Your Changes Up===

To send your changes back up to the main opentaps git repository, you would need to do a
$ git push git@gitorious.org:opentaps/opentaps.git

To commit a branch other than the one you are currently on (see below), use
$ git push git@gitorious.org:opentaps/opentaps.git name-of-branch

If you get this error message:
! [rejected] master -> master (non-fast-forward)
It means that your version is out of date, and you need to do a <tt>git fetch</tt> to bring your version of the day first before pushing up your changes.
Permission denied (publickey).
You need to upload your public key, usually </tt>~/.ssh/id_rsa.pub</tt>, to your profile on gitorious.

===Branching===

First let's take a look at what branches are available:
<pre>
$ git branch -a
* master
remotes/origin/HEAD -> origin/master
remotes/origin/master
</pre>

The current branch you're on is the one marked with a "*". The branches which start with "/remotes/" are from remote locations, such as gitorious, where you cloned opentaps. You can't really work with those.

To create your own branch,
<pre>
$ git branch dataimport
$ git branch -a
dataimport
* master
remotes/origin/HEAD -> origin/master
remotes/origin/master
</pre>

Now, to start working with your new branch, you need to switch to it. '''The <tt>git checkout</tt> command is actually for switching between branches, like <tt>svn switch</tt>''':
<pre>
$ git checkout dataimport
Switched to branch 'dataimport'
$ git branch -a
* dataimport
master
remotes/origin/HEAD -> origin/master
remotes/origin/master
</pre>

Here's something else that will seem strange at first about branches in git: If you make changes but do not commit them, and then switch to a different branch, git will give you a diff against the other branch. So, for example:
<pre>
$ git checkout dataimport
$ vi my-file
# make some changes
$ git diff
# will show the changes you just made against your current branch, or dataimport
$ git checkout master
$ git diff
# will show the same changes, but now against the master branch you just switched to
</pre>

You would need to commit the changes to one branch or another. Then, when you switch between the branches with <tt>git checkout</tt> or see a log of your committed changes with <tt>git log</tt>, you will see the difference if you are on one branch versus another.

===Deleting a Branch===

If you need to get rid of a branch,
$ git branch useless-branch
$ git branch -d useless-branch

===Copying Remote Branches===

If you have multiple remote branches, so that
<pre>
$ git branch -a
* pro-master
remotes/origin/1447
remotes/origin/1474
remotes/origin/1487
remotes/origin/HEAD -> origin/pro-master
remotes/origin/master
remotes/origin/pro-master
</pre>

You should make a local branch which copies a remote branch first before working with it:
$ git checkout -b 1447 origin/1447

This will copy the <tt>origin/1447</tt> branch to <tt>1447</tt>:
$ git branch -a
<pre>
* 1447
pro-master
remotes/origin/1447
remotes/origin/1474
remotes/origin/1487
remotes/origin/HEAD -> origin/pro-master
remotes/origin/master
remotes/origin/pro-master
</pre>

Otherwise, if you try to checkout to a remote branch directly, git will get confused:
$ git checkout origin/1447
$ git branch -a
* (no branch)
pro-master
remotes/origin/1447
...

===Resetting to a Remote Branch===

Sometimes the remote branch may actually "fall behind" your local branch, so that when you use <tt>git fetch</tt> and <tt>git rebase</tt>, git could still not correctly mirror it. This might happen if you went back on the remote branch, for example to remove some bad commits, and then moved forward again. For example, this e-mail from git tells you that:
<pre>
This update added new revisions after undoing existing revisions. That is
to say, the old revision is not a strict subset of the new revision. This
situation occurs when you --force push a change and generate a repository
containing something like this:

* -- * -- B -- O -- O -- O (e678fc2bb071e8d57d428a7c8cb25bc2cfbe28e5)
\
N -- N -- N (007ba5038c62421d458a02fb66889d271292a48f)
</pre>

At other times, you may just want to get rid of all your local commits and go back to wherever the remote branch is right now, but <tt>git rebase</tt> would just merge the changes from the remote branch to your local branch, and not get rid of your commits.

In either case, you can solve the problem with a <tt>git reset</tt>, for example:
$ git reset --hard origin/1447

Before doing this though, you could save your local branch in another branch first:
$ git branch clone-my-1447-branch
$ git reset --hard origin/1447

and then later, if you ever need it back, you can always use <tt>git rebase</tt>
$ git rebase 1447 clone-my-1447-branch

===Reversing Pushed Changes===

Sometimes you or somebody else might have pushed changes accidentally to the remove repository. To get rid of them, first get a log or history of the push commits:
$ git log

Then, use <tt>git reset</tt> to push back to a particular come it, identified by its SHA1 sequence from the log. For example:
$ git reset --hard 6bb3dc30bc0c8fc36421474cf9376d658ee643aa

Sometimes just the first few letters and numbers of the sequence, such as <tt>6bb3dc</tt> would do.

After you've done the reset, you need to push it back to the server. However, if you just pushed your branch, you will get an error message:
<pre>
$ git push git@gitorious.org:opentaps/opentaps.git master
To git@gitorious.org:opentaps/opentaps.git
! [rejected] master -> master (non-fast-forward)
error: failed to push some refs to 'git@gitorious.org:opentaps/opentaps.git'
To prevent you from losing history, non-fast-forward updates were rejected
Merge the remote changes before pushing again. See the 'Note about
fast-forwards' section of 'git push --help' for details.
</pre>

To really push it, you would need to add a <tt>+</tt> before your branch name:
<pre>
$ git push git@gitorious.org:opentaps/opentaps.git +master
Total 0 (delta 0), reused 0 (delta 0)
=> Syncing Gitorious... [OK]
To git@gitorious.org:opentaps/opentaps.git
+ 6398f5f...6bb3dc3 master -> master (forced update)
</pre>

===Fixing Commits Which Have Not Been Pushed===

If you have committed changes but have not pushed him yet, you have several ways of fixing them:
* git reset --hard origin/xxx : you will lose all the local commits and changes in your current branch
* git commit --ammend : you can use the ammend flag to "fix" the previous commit
* git reset XXX : without --hard it only resets the branch marker, but keeps the changes, so you can recommit the changes in a different way or fix them / etc ..
* git rebase -i XXX : opens an editor with the list of commits from XXX to your current branch state and you can remove one of those commits / reorder them / merge some together / etc ..

===Merging===

You can merge the changes from branch into another by switching to the target branch first, then doing a <tt>git merge</tt>. If you want to get the changes from a remote branch, you should <tt>git fetch</tt> and <tt>git rebase</tt> first. For example,
$ git fetch
$ git rebase origin/master master
$ git checkout dataimport
$ git merge master

This sequence gets all the updates from the remote git server, then updates the local copy of the master branch from the remote one. Next, I switched over to the dataimport branch. Finally, I merged the changes from the master branch to the dataimport branch.

Once you've done this, you may want to send the merged version of your local branch back to the remote repository. In that case, you must push again:
$ git push dataimport

Note that you do not need to commit first, because the merge happens on the local repository, so there are no uncommitted changes against the local repository.

You can always undo a rebase
$ git rebase --abort

===Merge Request===

Here's an example of something that would be a lot of work with subversion but almost trivial with git:

git pull git://gitorious.org/opentaps/opentaps.git refs/merge-requests/6
git push git://gitorious.org/opentaps/opentaps.git

I've just pulled a merge request from our gitorious repository, which are automatically merged into their branches in my local git repository, and then I pushed them back to gitorious.

====Clean Merge Requests====

Normally when working on a branch one would sometime have to merge the changes from the trunk into it in order to keep working on up-to-date code.
However when making a merge request this can result in a lot of those merges making the request harder to review.

When possible, instead of merging the trunk into the working branch one could rebase the working branch on top of the trunk.
For example if the trunk (from gitorious) is ''master'' and the working branch is ''my-feature''

git rebase master my-feature

===Experimenting with Git===

When you are first working with git, try this from any branch:
$ git branch tmp

This will copy it to a branch called <tt>tmp</tt>. You can then do whatever you want, such as
$ git reset XXX --hard

If later you decide that's not what you wanted, you can try to get it back with
$ git reset --hard tmp

Also, you can use
$ git reflog

to get a history.

===Extracting Diff from History===

To get historical changes from git, you can use <tt>git diff</tt> like this:
$ git diff 7cc3f0ce846952196dde68c62595f9 0069e2e46ad591bf4b7cf169d493b9

This will produce a diff file which you can then use the <tt>patch</tt> command to apply to other files.

Note that <tt>git diff</tt> parameters are in opposite sequence of <tt>svn diff</tt>:

$ svn diff <earlier>:<later>

is the same as
$ git diff <later> <earlier>

===Working with Additional Remote Repositories===

The other neat thing about git is that you can add additional remote repositories. For example, you may have cloned your own repository, but then you want to merge in changes from opentaps, or merge some of your changes back against opentaps. You can do this by adding the gitorious opentaps:
$ git remote add gitorious git://gitorious.org/opentaps/opentaps.git
$ git fetch -all
....
From git://gitorious.org/opentaps/opentaps
....
* [new branch] master -> gitorious/master

Now if you check your branches, you will see that there is a new <tt>remotes/gitorious/master</tt> branch:
$ git branch -a
....
remotes/gitorious/master

To merge in from gitorious opentaps:
$ git merge gitorious/master

(That's it!)

To merge back to opentaps, you need to create a patch file
$ git diff -p gitorious/master origin/master

or just the specified directories:
$ git diff -p gitorious/master origin/master -- opentaps
$ git diff -p gitorious/master origin/master -- opentaps/crmsfa opentaps/financials

and use the patch file for merging.

==Other Notes==

===File Formats===

With more frequent branching and merging, it's important that you keep file formats consistent and avoid Unix/Windows file differences. Make sure your editor is set to use Unix line terminations (use LF instead or CRLF). '''Before pushing to GIT, make sure your commit does not change the line terminations!''' Use $ git diff, and you will see the diff change all the file instead of just the relevant part.

If you are not sure about your editor you can also try to find the DOS2UNIX.EXE utility to set the proper formating.

===Untracked Files===

To get a list of files not tracked by git,
$ git status

You can remove files which are not tracked by git with
$ git clean -x -f -d

It will remove all the untracked files and directories from your current directory.

==References==
* http://git.or.cz/course/svn.html
* http://www-cs-students.stanford.edu/~blynn/gitmagic/ch01.html
* http://jonas.iki.fi/git_guides/HTML/git_guide/
* http://www.bitsun.com/documents/gittutorcn.htm
* http://wenku.baidu.com/view/a3490b22192e45361066f56a.html
* http://wiki.eclipse.org/EGit/User_Guide

How To Use Monitoring Agents

2010-07-29T01:20:07Z

Jwickers: /* Example: RPM Relic */

Most monitoring agents will need to be declared as arguments to the JVM.
In order to do that, dimply edit the ''startofbiz.sh'' (or .bat on windows) script and replace the following:

VMARGS="$MEMIF $MISC $DEBUG $RMIIF $ADMIN"

By:

MONITORING="the agent parameters"
VMARGS="$MEMIF $MISC $DEBUG $RMIIF $ADMIN $MONITORING"

=== Example: JConsole ===

http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html

MONITORING="-Dcom.sun.management.jmxremote"

Then start Opentaps with the ''startofbiz.sh'' script and use ''JDK_HOME/bin/jconsole'' to connect to the opentaps JVM and start monitoring.

=== Example: RPM Relic ===

http://rpm.newrelic.com

First download the zip file containing the jar and download the YML file (available on the same page). Unzip the zip file and put the YML file in the same directory.

MONITORING="-javaagent:/full/path/to/newrelic.jar"

Then start Opentaps with the ''startofbiz.sh'' and you should start receiving data on their dashboard.

Opentaps Technical Reference

2010-06-04T00:28:47Z

Jwickers: /* General Information */

==Technical Reference==

''These documents are for developers who plan on customizing or extending opentaps''

===General Information===

* [[opentaps Release Process]]
* [[BPM Integration|SOA and BPM]]
* [[Importing Data with Dataimport]]
* [[opentaps Coding Standards]]
* [[opentaps User Interface Guidelines]]
* [[Managing Customizations with Upgrades]]
* [[How to Use Git: a Tutorial]]
* [[How To Use Monitoring Agents]]

===Developer Documentation===

* [[Technical Highlights of opentaps 1.4]]
* [http://www.opensourcestrategies.com/ofbiz/tutorials.php ofbiz framework tutorials]
* [[Domain Driven Architecture]]
* [[Using the Query Tool]]
* [[Base Entity Classes]]
* [[POJO Service Engine]]
* [[Java Wrapper for OFBiz Services]]
* [[Java Classes for Constants]]
* [[Managing Your Configuration Files]]
* [[Unit Testing]]
* [[Selenium UI Testing]]
* [[Working with the Domain Driven Architecture]]
* [[opentaps Hibernate Integration]]
* [[opentaps Search Feature]]
* [[How to use the opentaps Form Macros]]
* [[opentaps Ajax Pagination Framework]]
* [[Screen Widget Actions in Java]]
* [[Writing an ofbiz Container]]
* [[Checkstyle development tool]]
* [[Aspect Oriented Programming in opentaps]]
* [[Optimizations in Javascripts and CSS files]]
* [[How to Use Java BigDecimal: A Tutorial]]

==== opentaps and Google Web Toolkit ====
* [[Introduction to Google Web Toolkit (GWT)]]
* [[opentaps Google Web Toolkit]]
* [[Debugging GWT with Firebug]]
* [[Creating a Widget with Google Web Toolkit and opentaps]]

===Tips and Tricks===
* [[Creating and Applying Patches]]
* [[Extending opentaps]]
* [[Working with SSL]]
* [[Avoiding Database Deadlocks]]
* [[Database Tips]]
* Source Code Repository Management:
** [[SVN Tips]]
** [[How to use SVK]]
* [[Trac Tips]]
* [[CSS Display Bugs in IE]]
* [[Performance Analysis and Troubleshooting]]
* [[Running Tsung against opentaps server]]
* [[Solving the error unable to rename old file FOO to temporary file on Windows]]

===API and Technical Design Reference===
* [http://www.opentaps.org/javadocs opentaps JavaDocs]
* [[LiveCatalog XML-RPC API]]
* [[Amazon Integration]]
* [[Manufacturing Model]]
* [[Configuring the POS Store]]
* [[Configuring Authorize.NET]]
* [[Implementing CVV Security Code Checking]]

==opentaps Architecture==
* [[Examples of Modularity]]

==Recommended Reading==

<pre>
Show me your flowcharts and conceal your tables, and I'll continue to be mystified.
Show me your tables, and I won't usually need your flowcharts; they'll be obvious.
</pre>
-- [http://www.amazon.com/exec/obidos/redirect?tag=opensourcestr-20&path=ASIN/0201835959 The Mythical Man Month by Fred Brooks]

Even after four decades, and long after the word "flowchart" has been replaced by "UML", data models still play a central role in software design. The following three books will give you three different perspectives on data modeling for enterprise applications and help you understand the heart of opentaps. You should read all three to get a balanced perspective:
* [http://www.amazon.com/exec/obidos/redirect?tag=opensourcestr-20&path=ASIN/0471380237 Data Model Resource Book, Volume 1.] -- This comprehensive volume and approaches it from a relational perspective for transactional systems.
* [http://www.amazon.com/exec/obidos/redirect?tag=opensourcestr-20&path=ASIN/0321125215 Domain Driven Design] -- This book approaches the design of transactional applications from an object-oriented perspective.
* [http://www.amazon.com/exec/obidos/redirect?tag=opensourcestr-20&path=ASIN/0471200247 Data Warehouse Toolkit] -- This book gives a comprehensive treatment from the analytical perspective.

Other helpful references:
* [http://www.amazon.com/exec/obidos/redirect?tag=opensourcestr-20&path=ASIN/0131487876 Opentaps Source Licensing] -- If you want to learn more about open source software licenses, read this book instead of all the mailing list graffiti.
* [http://www.amazon.com/exec/obidos/redirect?tag=opensourcestr-20&path=ASIN/0321344758 Don't Make Me Think], or I will hate your user interface.

How To Use Monitoring Agents

2010-06-04T00:27:34Z

Jwickers: New page: Most monitoring agents will need to be declared as arguments to the JVM. In order to do that, dimply edit the ''startofbiz.sh'' (or .bat on windows) script and replace the following: V...

Most monitoring agents will need to be declared as arguments to the JVM.
In order to do that, dimply edit the ''startofbiz.sh'' (or .bat on windows) script and replace the following:

VMARGS="$MEMIF $MISC $DEBUG $RMIIF $ADMIN"

By:

MONITORING="the agent parameters"
VMARGS="$MEMIF $MISC $DEBUG $RMIIF $ADMIN $MONITORING"

=== Example: JConsole ===

http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html

MONITORING="-Dcom.sun.management.jmxremote"

Then start Opentaps with the ''startofbiz.sh'' script and use ''JDK_HOME/bin/jconsole'' to connect to the opentaps JVM and start monitoring.

=== Example: RPM Relic ===

http://rpm.newrelic.com

First download the zip file containing both the jar and yml files, and unzip it in a directory.

MONITORING="-javaagent:/full/path/to/newrelic.jar"

Then start Opentaps with the ''startofbiz.sh'' and you should start receiving data on their dashboard.

How To Use Monitoring Agents

2010-06-04T00:27:34Z

Jwickers: Protected "How To Use Monitoring Agents": Sysop page [edit=sysop:move=sysop]

Most monitoring agents will need to be declared as arguments to the JVM.
In order to do that, dimply edit the ''startofbiz.sh'' (or .bat on windows) script and replace the following:

VMARGS="$MEMIF $MISC $DEBUG $RMIIF $ADMIN"

By:

MONITORING="the agent parameters"
VMARGS="$MEMIF $MISC $DEBUG $RMIIF $ADMIN $MONITORING"

=== Example: JConsole ===

http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html

MONITORING="-Dcom.sun.management.jmxremote"

Then start Opentaps with the ''startofbiz.sh'' script and use ''JDK_HOME/bin/jconsole'' to connect to the opentaps JVM and start monitoring.

=== Example: RPM Relic ===

http://rpm.newrelic.com

First download the zip file containing both the jar and yml files, and unzip it in a directory.

MONITORING="-javaagent:/full/path/to/newrelic.jar"

Then start Opentaps with the ''startofbiz.sh'' and you should start receiving data on their dashboard.

Upgrading from opentaps 1.0 to opentaps 1.4

2010-03-04T16:07:16Z

Jwickers: /* Data Changes */

__TOC__

== Data Changes ==

* Configuration of GL accounts for invoice writeoffs have been changed. Instead of using <tt>GlAccountTypeDefault</tt>, they are now configured with <tt>InvoiceAdjustmentGlAccount</tt> with the adjustment type "WRITEOFF"
* If you have custom UI labels, they may be loaded by adding them to <tt>LabelConfiguration.properties</tt> in <tt>opentaps-common/config/</tt>
** If previously you were using <tt>UtilMessage.registerLabelMap()</tt> to load custom labels, you may now remove all calls to this function as it is no longer needed.
* Run the upgrade SQL script in hot-deploy/opentaps-common/scripts/sql for the following:
** <tt>ProductAverageCost</tt> has been re-factored to use a single productAverageCostId as its primary key. The script will alter the table and automatically fill in its values and update <tt>SequenceValueItem</tt> so that opentaps will generate correct future keys.
* Add the following to your custom component's build.xml:
<fileset dir="${ofbiz.dir}/hot-deploy/opentaps-common/lib" includes="*.jar"/>
<fileset dir="${ofbiz.dir}/hot-deploy/opentaps-common/lib/hibernate" includes="*.jar"/>

* Rebuild opentaps
<pre>
ant
</pre>

* Run the ant import ext seed in command window:
<pre>
ant run-install-extseed
</pre>

* Start opentaps

* Run the following services to set summary fields:
** <tt>recalcAllEmptyAmountsPayments</tt>
** <tt>recalcAllEmptyAmountsInvoices</tt>
** <tt>updatePostedAmountAcctgTrans</tt>
* Run the service to populate primary contact data for all parties:
** <tt>opentaps.setSupplementalDataForAllParties</tt>
* Run the following service to create hibernate search index files:
** <tt>opentaps.createHibernateSearchIndex</tt>

== Coding Changes ==

Changes in the ofbiz framework would require the following changes to your code:

=== URL Parameter Security ===

You can no longer pass parameters to a service request directly in the URL. These requests must be part of a POST form. To make buttons work as before, you need to change them to forms and then activate them with javascript. For example, in earlier versions, you could have a button to delete a lead like this:
<#assign update_options = update_options + "<a class='subMenuButtonDangerous'
href='deleteLead?leadPartyId=" + partySummary.partyId + "'>" + uiLabelMap.CommonDelete + "</a>" />

In opentaps 1.4, you must do it this way:
<form name="deleteLeadForm" method="post" action="<@ofbizUrl>deleteLead</@ofbizUrl>"/>
<@inputHidden name="leadPartyId" value="${partySummary.partyId}"/>
</form>
<#assign update_options = update_options + "<a class='subMenuButtonDangerous'
href='javascript:document.deleteLeadForm.submit()'>" + uiLabelMap.CommonDelete + "</a>" />

For your convenience, there is also a new macro to do this (see ''form'' and ''submitFormLink'' in opentapsFormMacro.ftl):
<@form name="deleteLeadForm" url="deleteLead" leadPartyId=partySummary.partyId />
<#assign update_options>${update_options}<@submitFormLink form="deleteLeadForm" text=uiLabelMap.CommonDelete class="subMenuButtonDangerous" /></#assign>

The ''form'' macro makes hidden inputs for all parameters (except ''name'', ''url'' and ''method'' that are used to define the form element itself), and also accept nested elements for more complex cases.

For the cases where a form has to be used for multiple items, for example when you have an Update form block which must include multiple remove links, instead of writing a JavaScript handler which passes the item Ids to the form before submitting, you can do:

<@form name="removeReturnItemAction" url="removeReturnItem" returnId=returnId returnItemSeqId="" />
<@form name="updateReturnItemsAction" url="updateReturnItems" returnId=returnId>
<#list returnItems as item>

<@submitFormLinkConfirm form="removeReturnItemAction" text=uiLabelMap.CommonRemove returnItemSeqId=item.returnItemSeqId />
</#list>
</@form>

Also the new ''selectActionForm'' and ''actionForm'' can be used with ''form'' to define a drop-down menu where when an item (''actionForm'') is selected it submits the corresponding ''form'':
<@form name="deleteLeadForm" url="deleteLead" leadPartyId=partySummary.partyId />
<@form ... />
<@selectActionForm name="leadActions" prompt="${uiLabelMap.CommonSelectOne}">
<@actionForm form="deleteLeadForm" text="${uiLabelMap.CommonDelete}"/>
<@actionForm .../>
<@selectAction/>

=== Service and HTML inputs ===

As a security feature, the services will filter any input with HTML by default. Some services still require HTML (like emails or templates services) and to allow that there is a new ''allow-html'' parameter. For example:

<attribute name="content" type="String" mode="IN" optional="false" allow-html="safe"/>
<override name="mergeFormText" allow-html="safe"/>

=== Form Widget Changes ===

Form widget URL parameters should be specified with <tt>parameter</tt> tag now, instead of in the URL:
<pre>
- <hyperlink description="${contactListName} (${contactListId})" target="viewContactList?contactListId=${contactListId}">
+ <hyperlink description="${contactListName} (${contactListId})" target="viewContactList">
+ <parameter param-name="contactListId" from-field="contactListId"/>
</hyperlink>
</pre>
Do not have it both in the URL and as a <tt>parameter</tt>, or the parameter will be on the form twice and be passed incorrectly.

=== Controller redirects ===

Redirects have been changed, now ''request-redirect'' will only copy the parameters that were in the URL string by default. To forward posted or service output parameter, use the ''redirect-parameter'' elements (one per parameter).
<response name="success" type="request-redirect" value="viewAccount">
<redirect-parameter name="partyId"/>
</response>
Also ''request-redirect-filter-param'' is now considered deprecated.

=== Js dateTime format ===

Js dataTime format in ftl have been changed, now the format will return html encode string which will cause the parse exception, you should use StringUtil.wrapString to avoid this issue. For example, in earlier versions, you could have define a js dataTime format variable like this:

<#assign dateFormat = Static["org.opentaps.common.util.UtilDate"].getJsDateTimeFormat(Static["org.opentaps.common.util.UtilDate"].getDateFormat(locale))/>

In opentaps 1.4, you must do it this way:

<#assign dateFormat = StringUtil.wrapString(Static["org.opentaps.common.util.UtilDate"].getJsDateTimeFormat(Static["org.opentaps.common.util.UtilDate"].getDateFormat(locale)))/>

=== BSH embedded in Forms ===

In Forms widgets you could embed bsh code in order to have more flexibility over the formatting. Those embedded scripts need to be changed to groovy to avoid classpath issues. Fortunately this is as simple as changing the ''${bsh:'' to ''${groovy:''

For example, in earlier versions, you could transform a party Id into the whole party name:

<field name="partyId" title="${uiLabelMap.ProductSupplier}">
<display description="${bsh:org.ofbiz.party.party.PartyHelper.getPartyName(delegator, partyId, false)} (${partyId})"/>
</field>

In opentaps 1.4, you must change it to:

<field name="partyId" title="${uiLabelMap.ProductSupplier}">
<display description="${groovy:org.ofbiz.party.party.PartyHelper.getPartyName(delegator, partyId, false)} (${partyId})"/>
</field>

=== UEL in Minilang ===

The ofbiz framework now supports unified express language (UEL) in the screen widgets and minilang simple methods. (See [http://docs.ofbiz.org/display/OFBTECH/Unified+Expression+Language+%28JSR-245%29+in+OFBiz ofbiz wiki])

One side effect is that code in simple methods, for example:
someHash.${someVariableAsKey}

In opentaps 1.4, you must change it to:
someHash[someVariableAsKey]

=== HTML escaping ===

The ofbiz framework now automatically encodes most of the data displayed on the page. In some cases this is not wanted, and to avoid escaping in form widget use ''encode-output="false"'' in the field element:
<field name="transactionDate" encode-output="false"><date-time/></field>

In the FTL templates use the ''StringUtil'' class:
${StringUtil.wrapString(someData)}

Some previous helper methods that constructed HTML code will not work anymore. For example ''PartyHelper.createViewPageLink'' has been replaced with the macro:
<@displayPartyLink partyId=partyId />

== Internationalization and Translations ==

In ofbiz09.04, translations are now in XML format instead of .properties. However, the old .properties translations are supported still as well.

Furthermore, it is possible to define a component with all your translations, instead of putting them into the various existing components. As an example, <tt>hot-deploy/translations</tt> in opentaps contains a full set of translations for opentaps to Bulgarian.

== Other Changes ==

In some cases the ''screenlet-title-bar'' used in some ofbiz forms and screens is not wanted, in that case simply wrap the form or screen section in a ''noTitleBar'' div.

For example ''ViewShipmentRouteInfo.ftl'' defines such a title, to hide it we added to the screen definition:

<container style="noTitleBar">
<platform-specific>
<html><html-template location="component://product/webapp/facility/shipment/ViewShipmentRouteInfo.ftl"/></html>
</platform-specific>
</container>

Optimizations in Javascripts and CSS files

2010-03-01T20:08:47Z

Jwickers: New page: == Javascripts == === Note on DOJO === The DOJO files can be combined using the packager included with the DOJO sources. The opentaps DOJO files are based on the 0.9.0 release. To make ...

== Javascripts ==

=== Note on DOJO ===

The DOJO files can be combined using the packager included with the DOJO sources. The opentaps DOJO files are based on the 0.9.0 release.

To make a packaged DOJO:
* get the release tarball with sources: dojo-release-0.9.0-src.tar.gz
* define the profile (set of modules included in a package) by creating util/buildscripts/profiles/opentaps.profile.js with:
dependencies = {
layers: [
{
name: "opentaps-dojo.js",
dependencies: [
"dojo.fx",
"dojo.dnd.source",
"dojo.dnd.manager",
"dojo.dnd.move",
"dojo.currency",
"dojo.data.JsonItemStore",
"dojo.data.JsonItemStoreAutoComplete",
"dijit.Tree",
"dijit.Dialog",
"dijit.form.window",
"dijit.form.Form",
"dijit.form.Button",
"dijit.form.ComboBox",
"dijit.layout.ContentPane",
"dijit.nls.loading"
]
}
],
prefixes: [
[ "dijit", "../dijit" ],
[ "dojox", "../dojox" ]
]
}
* in util/buildscripts : do ./build.sh profile=opentaps action=release copyTests=false
* get the files from release/dojo
* this includes a opentaps-dojo.js which will be used later

Note that for opentaps dome patches were applies (see the revision control system).

To include in a HTML page, the simple dojo.js must still be included first

=== Packing other JS files ===

From hot-deploy/opentaps-common/webapp/js:
* merge the various scripts
cat protoaculous.1.8.2.p1.6.1.min.js ../../../../framework/images/webapp/images/calendar_date_select.js opentaps.js selectall.js fieldlookup.js formwidget.js opentapsDisplayEffects.js opentapsWindow.js shortcuts.js jscalendar-1.0/calendar.js jscalendar-1.0/calendar-setup.js > opentaps-packed1.js
* pack with [[http://www.crockford.com/javascript/jsmin.html jsmin]]
jsmin <opentaps-packed1.js >opentaps-packed.js
* merge with the dojo package in hot-deploy/opentaps-common/webapp/js/dojo_0.90/dojo
cat opentaps-dojo.js ../../opentaps-packed.js > opentaps-dojo-packed.js

== CSS files ==

The CSS files where already merged, except the jscalendar CSS (since this is an external module), to merge it, in hot-deploy/opentaps-common/webapp/css
cat opentaps.css ../js/jscalendar-1.0/calendar-system.css > opentaps-packed.css

To further reduce the CSS file size an external CSS compressor can be used (for example http://www.cleancss.com/).